twbot.rb Library Reference

To try working a bot:

• Locate three files (twbot.rb, config.yml, rsspost-sample.rb) to a directory.
• Change the user name and password in config.yml to your bot's information.
• Change the URL for RSS in rsspost-sample.rb to your blog's (or like) RSS.
• Execute "ruby rsspost-sample.rb load" to add tweets.
• Execute "ruby rsspost-sample.rb post" to post a tweet to Twitter.

@config (instance variable)

A hash represents the content of the configuration file (The 2nd argument in TwBot#new). If content of @config is changed, the content of the configutration file is changed into the content of @config. (The configuration file is overwritten only if the program is properly ended.)

In @config, those keys are reserved for special situations. These values is recommended not to be changed unless needed.

• @config["login/"] : Twitter login name that posts messages.
• @config["password/"] : Twitter password of the account above.
• @config["data/***"]("***" is arbitary string) : List of messages. The 4th argument of TwBot#new (default: empty string) is embedded in "***". So by default, messages are stored/posted in @config["data/"] .
• @config["last_post/"] : The last posted message. Because same messages can not be posted continually to Twitter, if same message as @config["last_post/"] is going to be posted, additional string is added to the message in the list.

You can add keys in @config keeped for after running of program. (ex. @config["already_gotten"] in rsspost-sample.rb .) User-defined key should not contain "/" because other reserved keys may be defined in the future.

@list (instance variable)

The string with format of "data/***", where "***" is the 4th argument of TwBot#new (default: empty string). @config[@list] means specified list of messages.

@logmsg (instance variable)

Assign the message to @logmsg written to the log file. If program stops with exception, the value of @logmsg is ignored. (In this case, logged message is the exception information.)

TwBot#load_data() (private method)

Method for making messages the bot posts. This method have to return an array of strings. If no messages are newly added to the list, return empty array. You can set arrays to the returned array's elements instead of string.(The item-of-array arrays are called "internal arrays" for convenience.) If you do so, first element of an internal array is treated as the message, and second element of the internal array is treated as the value of "in_reply_to_status_id" (message ID to be replied).
You do not have to call the method load_data directly. This method is called in TwBot#new(TwBot#initialize).
When TwBot#load_data itself is called, exception "NotImplementedError" is raised. Make a new class inheriting TwBot, and re-define this method.

TwBot#new(mode, config_file, log_file = nil, list_name = '', keep_config = false, testmode = false)

Method for starting getting/posting messages.

• mode : Specify either of "load" or "post". If another string is specified, exception "ArgumentError" is raised.
  • If "load" is specified, call the method "load_data" and get an array of string for the bot. The array is added at the end of @config[@list] .
  • If "post" is specified, remove the first message in @config[@list] and post it to Twitter.
  
  From Version 0.14, You can specify a string formatted "post=####,@@@@" instead of the string "post". ("####" and "@@@@" are integers of any digits, and you can omit ",@@@@" part.) This format means twbot.rb will post messages #### times, and will retry posting until @@@@ failures are made. For example, to post 5 message and quit if an error occurred in posting, specify "post=5". Specifying simply "post" is equal to specifying "post=1,1".
• config_file : Specify configuration file. Configuration file must be written in YAML format.
• log_file : Specify log file. If nil is specified, log is not written to any file.
• list_name : Specify list name where posts are stored. "data/"+list_name is stored to the variable @list.
• keep_config : If this value is true, configuration file is not changed at the end of program. This parameter is used for testing script.
• testmode : If this value is true, the message is not posted to Twitter. This parameter has effect only if the 1st argument is "post". This parameter is used for testing script.

TwBot#get_followers()

Returns a hash for followers of current bot. Equivalent to TwBot.retrieve_followers(@config['login/'], @config['password/']).

TwBot#get_friends()

Returns a hash for friends of current bot. Equivalent to TwBot.retrieve_friends(@config['login/'], @config['password/']).

TwBot#follow(user)

Lets current bot follow the user. Equivalent to TwBot.make_following(@config['login/'], @config['password/'], user).

TwBot#unfollow(user)

Lets current bot not follow the user. Equivalent to TwBot.make_unfollowing(@config['login/'], @config['password/'], user).

TwBot#following_status(target)

Checks whether current bot follows and is followed by target. Equivalent to TwBot.check_following(@config['login/'], @config['password/'], target).

TwBot.remove_reply(str){ |username| ... }

Converts all replies (format of "@USERNAME") to "@ USERNAME"("@" + space + "USERNAME") in "str", and returns converted string. This method is used for avoiding excessive replying.
You can attach a block to this method. If so, "@USERNAME" is converted if the block (user name excluding "@" is given) returns true.

From ver0.15, not only half-width "@"'s but full-width "@"'s before the screen names are converted. (Because of the change in Twitter's specification)

# Example
puts TwBot.remove_reply("@user1 @user2 Hello!")
# This puts "@ user1 @ user2 Hello!".

puts TwBot.remove_reply("@user1 @user2 Hello!"){ |u| u =~ /1/ }
# This puts "@ user1 @user2 Hello!", because "user1" meets the condition
# in the block, but "user2" not.

TwBot.retrieve_followers(login, pass, retry_count = 3)

Retrieves all followers of the user login. pass should be the password of the user login. If there are retry_count errors of API calls, this method will stop retrieving.

Returns a hash whose format is

{:result => ["user1", "user2", ...],
 :error => [exception1, exception2, ...]}

where an array of the screen names of followers is set to :result, and an array of the exceptions occurred when retrieving to :error. If errors occurred for retry_count times, the value for :result will be nil.

TwBot.retrieve_friends(login, pass, retry_count = 3)

Retrieves all friends of the user login. The formats of the arguments and the return value are same as that of TwBot.retrieve_followers shown above.

TwBot.make_following(login, pass, user)

Let the user login be following the user user. pass should be the password of the user login.

If failed in following, this method will cause an exception, including if login already follows user. The exceptions are:

• Net::HTTPForbidden: In case login is following user
• REXML::********: In case Twitter API returns a non-XML string
• RuntimeError: In case Twitter API returns a XML string but the XML is not for "succeeded in following"

TwBot.make_unfollowing(login, pass, user)

Let login be not following user. pass should be the password of the user login.

If failed in un-following, this method will cause an exception, including if login does not follow user. The exceptions to be raised is same as that of TwBot.make_following (replace "following" by "not following").

TwBot.check_following(login, pass, target)

Check whether the user login follows the user target and the other way. pass should be the password of the user login.

Returns a hash of the format {:following => boolean1, :followed => boolean2}. (boolean1 and boolean2 are either of true or false.) boolean1 means whether login follows target, and boolean2 whether target follows login.