twbot2.rb - Twitter Bot Support Library in Ruby

twbot2.rb (new version)

• twbot2-0.20.zip(2010.05.16)

twbot.rb (old version)

• twbot-0.15.zip(2009.12.10)
• twbot-0.14.zip(2009.04.14)
• twbot-0.13.zip(2009.03.09)
• twbot-0.12.zip(2008.12.18)
• twbot-0.11.zip(2008.12.14)
• twbot-0.10.zip(2008.10.26)

2011年7月より、ダイレクトメッセージ関連のAPIが、古いOAuthトークンでは利用不可能になります。利用されたい場合は、再度認証をお願いします。なお再度認証を行うには、まずconfig.ymlファイルから'users/USERNAME'のエントリ（直下の'token'や'secret'も含む）を削除し、その後'ruby BOT_SCRIPT_NAME.rb add=USERNAME'を実行します。(2011.6.28)

twbot.rbの新しいバージョン「twbot2.rb」を公開開始しました。古いtwbot.rbはOAuthに対応しておらず、8月31日以降は利用出来なくなりますのでご注意下さい。なお、twbot.rbからtwbot2.rbへの移行は少ない労力で行えるようになっております。(2010.5.16)

twbot2.rbは、RubyにてTwitterのbot（プログラムにより自動的に発言を行うアカウント）作成を行う際に、その補助を行うライブラリです。どちらかといえばフレームワークに近いかもしれません。

特に、定期的に特定の位置からデータを取得し（RSSやTwitterのタイムラインなど）、それに基づいて発言を行うbotを作るのに適したものとなっています。

Rubyインタプリタの導入されている、定期的にプログラムを実行させるためのPC

• 定期的なプログラムの実行を行う機構としては、Unix系OSであればcron、Windowsであればタスクスケジューラなどがあります。（これらに関する詳細な説明は行いません）
• 電気代を考慮して、省電力なマシンを使ったり、省電力機能を利用するとよいでしょう。
• Rubyの環境について
  • Ruby 1.8および1.9の利用を推奨します。Ruby1.8.6, 1.8.7, 1.9.1でテストしています。
  • Ruby1.8/1.9の場合、標準添付のライブラリだけで動きます。
  • Ruby1.7以前での稼働は推奨しません。（yaml、rexmlライブラリ必須のため）

twbot.rbの中では、TwBotというクラスが定義されています。ただしTwBotはそのままで利用するものではなく、次の手順を踏む必要があります。

1. TwBotクラスを継承したクラスを定義する。
2. 継承先のクラスでload_dataメソッドを再定義する。
• load_dataメソッドは、そのbotが発言する内容の文字列を配列にして返すメソッドです。1文字列が1発言になり、先頭にある要素ほど先に投稿されます（キューの形になります）。
• 配列の要素を文字列の代わりに配列にすると（これを以下「内側の配列」と呼びます）、内側の配列の先頭の要素を投稿する本文、次の要素を「in_reply_to_status_id」の値（返信先の発言ID）とみなします。
3. 継承先のクラスのインスタンスを生成する。このとき
   • newの第1引数に「"init"」を与えると、設定ファイルにbotアカウントの認証情報を追加する手続きが行われる。
   • newの第1引数に「"load"」を与えると、そのbotが発言する内容をリストに追加し、投稿待ちの状態にする。
   • newの第1引数に「"post"」を与えると、リストの先頭の発言を取り出し、Twitterに投稿する。

例として、返信が来た件数をつぶやくbotのコードを示します（上記zipファイルにも同梱しています）。

#!/usr/bin/env ruby
# -*- coding: utf-8 -*-

$: << File.dirname(__FILE__)

require "twbot2"
require "rexml/document"

class SimpleBot < TwBot
  def load_data
    # =============================================================
    # What the bot talks should be defined in 'load_data' method.
    # This example is to fetch mentions to the bot and notify them.
    # =============================================================
    
    # ---------- fetch replies ----------
    
    # downloading the XML
    response = auth_http.get("/1/statuses/mentions.xml")
    xml = REXML::Document.new(response.body)
    
    # extracting only message IDs of the XML
    mentions_ids = xml.elements.to_a("/statuses/status/id")
    mentions_ids.map!{ |x| x.text.to_i }
    
    # ---------- exclude old replies ----------
    
    # If you create a new key in the Hash @config,
    # this will be kept in the config file.
    @config['last_id'] ||= 0
    
    # keeping the newest ID among the downloaded mentions
    new_last_id = mentions_ids.first
    
    # excluding the IDs representing old messages
    mentions_ids.reject!{ |m_id| m_id < @config['last_id'] }
    
    # renewing the newest ID
    @config['last_id'] = new_last_id
    
    # ---------- return the message to be posted ----------
    
    # The return value must be an array.
    # If you specify strings as the return value,
    # the bot will talk it as it is,
    # when you run 'ruby simplebot.rb post'.
    
    ["#{mentions_ids.size} new replies found!"]
  end
end

self_path = File.dirname(__FILE__)
ARGV.each do |mode|
  SimpleBot.new mode, "#{self_path}/config.yml", "#{self_path}/error.log"
end

これを起動する手順は以下の通りです。

1. 上記コード（simplebot.rb）とともに、「twbot2.rb」本体と「twbot2」ディレクトリを同一のディレクトリに置く。
2. コマンドラインにて「ruby simplebot.rb init」と入力し、アカウントの認証を行う。
3. コマンドラインにて「ruby simplebot.rb load」ないし「ruby simplebot.rb post」と入力する。返信の来た件数を発言リストに追加する際には「load」、発言をTwitterに投稿するときは「post」を指定する。

ポイントは、根本的に書かなければならないコードは「botが何を発言するか」だけであることです。それさえ書けばbotを作ることが出来ます。

• Help for twbot2.rb (PDF)
• Help for old twbot.rb

• 詳しいTwitterのAPIについては、公式ドキュメント（Twitter API Wiki / REST API Documentation）をご参照下さい。
• TwitterのAPIは、多くのものがXML形式かJSON形式を選択して取得できます。XMLに比べJSONの方が扱いやすいです（データがハッシュ・配列のみで表現されているため）。ただし、別途ライブラリのインストールが必要になります（Rubygems利用の場合、コマンドは「gem install json」となります）。

Version 0.10(2008.10.26)

初版公開

Version 0.11(2008.12.14)

同一の発言を2連続で投稿可能にした。これに伴い、@config変数に["last_post/"]キーを追加。

Version 0.12(2008.12.18)

Twitter運営からの認可を得て、twbot.rbからの投稿時に「from twbot.rb」と表示されるようにした。

Version 0.13(2009.03.09)

• Ruby1.9に対応させた。
• 「in_reply_to_status_id」を付与した発言を可能にした。

Version 0.14(2009.04.14)

• TwBot#new の第1パラメータの書式を拡張した。（従来の"post"に加え、"post=5,2"のような書式が可能になりました）
• Twitterのreplyの仕様変更に対応するため、クラスメソッド TwBot.remove_reply を追加した。

Version 0.15(2009.12.10)

• @が全角でもreplyとみなされるようになったため、メソッド TwBot.remove_reply を更新した。
• フォロー管理のメソッド（TwBot#get_followers, TwBot#get_friends, TwBot#follow, TwBot#unfollow, TwBot#following_status, TwBot.retrieve_followers, TwBot.retrieve_friends, TwBot.make_following, TwBot.make_unfollowing, TwBot.check_following）を追加した。

Version 0.20(2010.05.16)

OAuth対応のため一から書き直した。

(C)2008- H.Hiro(Maraigue)

twbot.rbの複製・改変の条件は、（新）BSDライセンスに合わせます。BSDライセンス（原文） BSDライセンス（参考訳）
簡単に言えば、このソフトは無保証であり、また再配布（改変した上での再配布含む）の場合にも元の著作権表示などの部分が記されている必要があります。

私が使いやすいように書いているため、使いにくい点があるかもしれません。あらかじめご了承下さい。要望は可能な限りお受けします。

スクリプトに関する報告は、Twitter/h_hiro_および、メールアドレスmain(あっとまーく)hhiro.netにお願いします。