Overview

Opening a Connection

Pass Net::Toc.new your screenname and password to create a new connection. It will return a Client object, which is used to communicate with the server.

 client = Net::TOC.new("screenname", "p455w0rd")

To actually connect, use Client#connect.

 client.connect

If your program uses an input loop (e.g., reading from stdin), you can start it here. Otherwise, you must use Client#wait to prevent the program from exiting immediately.

 client.wait

Opening a Connection - The Shortcut

If your program only sends IMs in response to received IMs, you can save yourself some code. Net::TOC.new takes an optional block argument, to be called each time a message arrives (it is passed to Client#on_im). Client#connect and Client#wait are automatically called.

 Net::TOC.new("screenname", "p455w0rd") do | message, buddy |
   # handle the im
 end

Receiving Events

Client supports two kinds of event handlers: Client#on_im and Client#on_error.

The given block will be called every time the event occurs.

 client.on_im do | message, buddy |
   puts "#{buddy.screen_name}: #{message}"
 end
 client.on_error do | error |
   puts "!! #{error}"
 end

You can also receive events using Buddy#on_status. Pass it any number of statuses (e.g., :away, :offline, :available, :idle) and a block; the block will be called each time the buddy’s status changes to one of the statuses.

 friend = client.buddy_list.buddy_named("friend")
 friend.on_status(:available) do
   friend.send_im "Hi!"
 end
 friend.on_status(:idle, :away) do
   friend.send_im "Bye!"
 end

Sending IMs

To send an instant message, call Buddy#send_im.

 friend.send_im "Hello, #{friend.screen_name}!"

Status Changes

You can modify your state using these Client methods: Client#go_away, Client#come_back, and Client#idle_time=.

 client.go_away "Away"
 client.idle_time = 600 # ten minutes
 client.come_back
 client.idle_time = 0 # stop being idle

It is not necessary to call Client#idle_time= continuously; the server will automatically keep track.

Examples

Simple Bot

This bot lets you run ruby commands remotely, but only if your screenname is in the authorized list.

 require 'net/toc'
 authorized = ["admin_screenname"]
 Net::TOC.new("screenname", "p455w0rd") do | message, buddy |
   if authorized.member? buddy.screen_name
     begin
       result = eval(message.chomp.gsub(/<[^>]+>/,"")) # remove html formatting
       buddy.send_im result.to_s if result.respond_to? :to_s
     rescue Exception => e
       buddy.send_im "#{e.class}: #{e}"
     end
   end
 end

(Slightly) More Complicated and Contrived Bot

If you message this bot when you’re available, you get a greeting and the date you logged in. If you message it when you’re away, you get scolded, and then pestered each time you become available.

 require 'toc'
 client = Net::TOC.new("screenname", "p455w0rd")
 client.on_error do | error |
   admin = client.buddy_list.buddy_named("admin_screenname")
   admin.send_im("Error: #{error}")
 end
 client.on_im do | message, buddy, auto_response |
   return if auto_response
   if buddy.available?
     buddy.send_im("Hello, #{buddy.screen_name}. You have been logged in since #{buddy.last_signon}.")
   else
     buddy.send_im("Liar!")
     buddy.on_status(:available) { buddy.send_im("Welcome back, liar.") }
   end
 end
 client.connect
 client.wait

Simple Interactive Client

Use screenname<<message to send message. <<message sends message to the last buddy you messaged. When somebody sends you a message, it is displayed as screenname>>message.

 require 'toc'
 print "screen name: "
 screen_name = gets.chomp
 print "password: "
 password = gets.chomp

 client = Net::TOC.new(screen_name, password)

 client.on_im do | message, buddy |
   puts "#{buddy}>>#{message}"
 end

 client.connect

 puts "connected"

 last_buddy = ""
 loop do
   buddy_name, message = *gets.chomp.split("<<",2)

   buddy_name = last_buddy if buddy_name == ""

   unless buddy_name.nil? or message.nil?
     last_buddy = buddy_name
     client.buddy_list.buddy_named(buddy_name).send_im(message)
   end
 end