cereal 0.1.8

data/CHANGES

@@ -0,0 +1,57 @@
+2009-03-30 v0.1.8 ross
+
+* lib/connection.rb (handle_line): Curbed a nasty memory leak by manually instantiating garbage collection. Residential memory usage should be more stable now.
+
+2009-03-13 v0.1.7 ross
+
+* lib/cereal.rb: All colors and text attributes now work correctly! Yay!
+
+2009-03-13 v0.1.6 ross
+
+* lib/cereal.rb (confirm_nick): Added @connection.temp_nick assignment.
+
+* lib/connection.rb: Added attr_accessor for @temp_nick.
+
+Fixes #6.
+
+2009-02-23 v0.1.5 ross
+
+* lib/cereal.rb (kick, ban): Methods added.
+
+2009-02-23 v0.1.4 ross
+
+* lib/connection.rb (initialize, receive_data): Added @incomplete_line_buffer to hold incomplete lines received from the server (lines not ending in a CR-LF or \r\n pair) until we receive the complete line. This should fix issues with large channels not reporting the correct number of users, etc.
+
+2009-02-23 v0.1.3 ross
+
+* lib/connection.rb (send_data): Added simplest fix ever that finally rids us of EventMachine complaining about sending data after closing a connection. OH GOD, THIS IS SO SATISFYING.
+
+* lib/cereal.rb: Updated version number to 0.1.3.
+
+2009-02-21 v0.1.2 jon
+
+* lib/connection.rb (handle_line): Moved on_quit callback to begining of block. This allows any on_quit callback to find the channels that the user was in before being removed from the channel list. (Might want a better way to do this, possibly grab a list of channels the user was in and pass it as an argument? Same thing with other blocks such as nick change.)
+
+2009-02-21 v0.1.2 ross
+
+* cereal.gemspec: Modified to pull gem version straight from lib/cereal.rb. No more updating! Also added auto updating of spec.date.
+
+2009-02-21 v0.1.2 ross
+
+* lib/cereal.rb (channels): Added. Method to grab hash of currently inhabited channels.
+
+2009-02-21 v0.1.1 ross
+
+* cereal.gemspec: Changed gem version to 0.1.1 to match actual Cereal version!
+
+2009-02-21 v0.1.1 ross
+
+* lib/cereal.rb (get_users): Added. Method to grab array of Cereal::User objects for a given channel that the bot is in.
+
+* lib/connection.rb: Added attr_reader for @channels. Used by Cereal::Bot#get_users.
+
+* cereal.gemspec: Added Jon R. to authors list.
+
+2009-02-17 ross
+
+* Initial import to SVN!

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Ross Paffett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,86 @@
+= Cereal
+This package contains Cereal, an event-driven IRC framework built on
+EventMachine and inspired by Paul Mutton's excellent
+PircBot[http://jibble.org/pircbot.php] IRC framework for Java.
+
+Cereal has the following features:
+
+* Easy to use! Cereal is designed for quick-and-easy implementation, just like
+  PircBot. Your first bot can be set up by overriding a single class.
+
+* Your specific functionality is easily added by overriding logically-named
+  methods, like +on_message+.
+
+Be sure not to confuse _Cereal_ and _CerealBot_. Cereal is a standalone IRC
+framework. By itself, Cereal does nothing. CerealBot[http://cerealbot.org],
+on the other hand, is a fully-featured IRC bot project by the same people who
+have ruined your life with Cereal.
+
+== Authors
+[Ross "Raws" Paffett] Lead developer.
+[Brian "TecnoBrat" S.] Inspiration, Ruby knowledge, general abuse.
+[Jon "Corgan" R.] Butts.
+
+== Download
+Cereal is currently hosted at cerealbot.org[http://cerealbot.org/].
+
+== Installation
+
+=== Gem Installation from Source
+Generate a Cereal .gem file and install it with the following commands:
+
+  rake package
+  gem install --local pkg/cereal
+
+Cereal will now be available to your Ruby code through rubygems:
+
+  require 'rubygems'
+  require 'cereal'
+
+You can clean up the package rake task files with:
+
+  rake clobber_package
+
+==== Generate Documentation
+You may generate documentation from source with the following command:
+
+  rake rdoc
+
+RDoc documentation will be created in the directory "doc".
+
+You can clean up the rdoc rake task files with:
+
+  rake clobber_rdoc
+
+== Simple Example
+Once installed, you can create your first bot!
+
+  require 'rubygems'
+  require 'cereal'
+  
+  class MyBot < Cereal::Bot
+    def initialize
+      super
+      @name = 'My Bot'
+      @nick = 'MyBot'
+      @verbose = true
+    end
+    
+    def on_connect(host)
+      puts "Connected to #{host}!"
+      
+      join('#cerealbot')
+      
+      msg('#cerealbot', 'Hi!')
+      msg('Corgan', 'Hello!')
+    end
+  end
+  
+  bot = MyBot.new
+  bot.connect('irc.freenode.net')
+
+== Documentation
+See the RDoc documentation for the Cereal module for more information.
+
+== License
+Cereal is available under the MIT license. See the file MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,30 @@
+# Rakefile for Cereal
+#
+# Copyright (c) 2009 Ross Paffett. Licensed under the MIT license:
+# http://www.opensource.org/licenses/mit-license.php
+
+require 'rubygems'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+load 'cereal.gemspec'
+
+# Generate rdoc documentation in ./doc/.
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'doc'
+  rd.main = 'README'
+  rd.rdoc_files.include('MIT-LICENSE', 'README', 'TODO', 'lib/**/*.rb')
+end
+
+# Create a Ruby Gem package.
+Rake::GemPackageTask.new(@@spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+# Package Cereal source into tarball
+Rake::PackageTask.new(@@spec.name, @@spec.version) do |p|
+  p.need_tar_gz = true
+  p.package_files.include('**/**')
+end

data/TODO

@@ -0,0 +1,9 @@
+= Cereal -- To Do List
+
+Send suggestions for this list to mailto:nobody@inparticul.ar! Actually, there
+is someone, but he doesn't have a proper public address set up yet.
+
+=== To Do
+* Document the rest of the library.
+* Write tests (is this even practically possible?).
+* Figure out if there's anything else to do.

data/lib/cereal.rb

@@ -0,0 +1,423 @@
+#!/usr/bin/env ruby
+
+# == Synopsis
+# Cereal is an IRC connection framework inspired (quite heavily) by
+# Paul Mutton's excellent PircBot[http://jibble.org/pircbot.php]
+# IRC library for Java.
+#
+# See documentation for the Cereal module for more information.
+#
+# == Author
+# Ross "Raws" Paffett
+#
+# == Copyright
+# Copyright (c) 2009 Ross Paffett. Licensed under the MIT license:
+# http://www.opensource.org/licenses/mit-license.php
+
+# Standard library
+require 'ostruct'
+require 'thread'
+
+# Rubygems
+require 'rubygems'
+require 'eventmachine'
+
+# Cereal library
+require 'connection.rb'
+require 'user.rb'
+
+# == Overview
+# Cereal is a Ruby framework for quickly and easily constructing IRC applications.
+#
+# TODO Actually write documentation or something. See Cereal::Bot for some
+# up-and-coming documentation for now.
+module Cereal
+  # Definitive version number of this release of Cereal.
+  VERSION = "0.1.8"
+  
+  # Colors
+  NORMAL = N = "\017"
+  BOLD = B = "\002"
+  UNDERLINE = UL = "\037"
+  REVERSE = REV = ITALIC = IT = "\026"
+  WHITE = "\0030"
+  BLACK = "\0031"
+  DARK_BLUE = NAVY = "\0032"
+  DARK_GREEN = FOREST = "\0033"
+  RED = "\0034"
+  MAROON = BROWN = "\0035"
+  PURPLE = "\0036"
+  ORANGE = OLIVE = "\0037"
+  YELLOW = "\0038"
+  GREEN = "\0039"
+  TEAL = "\00310"
+  CYAN = "\00311"
+  BLUE = "\00312"
+  MAGENTA = "\00313"
+  DARK_GRAY = "\00314"
+  LIGHT_GRAY = ASH = "\00315"
+  
+  class Bot
+    
+    attr_accessor :name, :login, :version, :finger, :message_delay, :verbose
+    attr_reader :nick
+    
+    def initialize
+      @name = 'Cereal'
+      @nick = @name
+      @login = 'cereal'
+      @version = "Cereal #{Cereal::VERSION} (Ruby #{RUBY_VERSION})"
+      @finger = 'You ought to be arrested for fingering a bot!'
+      @message_delay = 1.0
+      @verbose = false
+    end
+    
+    # Connect to a server, optionally specifying a port and password. This method
+    # starts the "main event loop." You may want to rescue +IrcError+ and/or
+    # +NickAlreadyInUseError+ here, as they may be raised upon a connection failure
+    # or other trouble.
+    # [_server_] The server hostname to connect to.
+    # [[_port_]] The port to connect to. Most IRC servers use port 6667 or similar.
+    # [[_password_]] The password to connect to the server with. A value of +nil+
+    #                (the default) will cause Cereal to skip this step.
+    def connect(server, port=6667, password=nil)
+      EventMachine::run {
+        @connection = EventMachine::connect(server, port, Cereal::Connection,
+            :bot => self, :password => password)
+      }
+    end
+    
+    # Add a line to the log. The default behavior is to output to STDOUT using the
+    # "PircBot" log format, which is recognized by pisg[http://pisg.sourceforge.net/],
+    # the Perl IRC Statistics Generator. This is only done if +@verbose+ is set to +true+.
+    #
+    # The PircBot log format is described as each line beginning with an integer that
+    # is the number of milliseconds since the epoch, followed by a single space, " ",
+    # then the log message. Outgoing messages are prefixed by ">>>" immediately
+    # following the space character after the timestamp:
+    #
+    #   1233871496459 >>>NICK Wheaties
+    #   1233871496459 >>>USER wheaties 0 * :Botfast of Champions!
+    #   1233871496488 :ravaged.mule.anus 001 Wheaties :Welcome to the Internet Relay Network Wheaties!~wheaties@Stig
+    # [_line_] The line to add to the log.
+    def log(line)
+      puts (Time.now.to_f * 1000).to_i.to_s + " #{line}" if @verbose
+    end
+    
+    # Returns an array of Cereal::User objects representing the users in the specified
+    # channel. Note that the bot must be in a channel to be aware of its users. In addition,
+    # this method may return an incomplete list of the bot has not received the entire user
+    # list for a channel immediately after joining. To be sure you receive a full list, you
+    # may want to override on_user_list instead.
+    # [_channel_] The channel to fetch an array of Cereal::User objects for.
+    def get_users(channel)
+      channel.downcase!
+      @connection.channels.fetch(channel, {}).keys
+    end
+    
+    # Returns a hash of channels that the bot is currently in. The hash's keys are strings representing
+    # the channel name, so that <code>channels.keys</code> will return an array of channel name strings.
+    # The hash's values are arrays of Cereal::User objects representing the users in that channel, which
+    # is the same data returned by get_users.
+    def channels
+      @connection.channels
+    end
+    
+    # Join a channel with an optional key.
+    # [_channel_] The channel to join.
+    # [[_key_]] The key that will be used to join the channel.
+    def join(channel, key=nil)
+      send_raw("JOIN #{channel}" + (key.nil? ? '' : " #{key}"))
+    end
+    
+    # Part a channel with an optional reason.
+    # [_channel_] The channel to leave.
+    # [[_reason_]] The reason for parting the channel.
+    def part(channel, reason=nil)
+      send_raw("PART #{channel}" + (reason.nil? ? '' : " :#{reason}"))
+    end
+    
+    # Quit from the IRC server with an optional reason.
+    # [[_reason_]] The reason for quitting the server.
+    def quit(reason = '')
+      @connection.send_data("QUIT :#{reason}")
+    end
+    
+    # Attempt to kick a user from a channel, optionally giving a reason. This
+    # action may require the bot have operator status in the channel.
+    # [_channel_] The channel to kick the user from.
+    # [_nick_] The nick of the user to kick.
+    # [[_reason_]] The reason for kicking the user.
+    def kick(channel, nick, reason='')
+      send_raw("KICK #{channel} #{nick} :#{reason}")
+    end
+    
+    # Ban a user from a channel. An example of a valid hostmask is "*!*compu@*.18hp.net".
+    # This may be used in conjunction with the kick method to permanently remove a user
+    # from a channel. This action may require the bot have operator status in the channel.
+    # Some IRC networks allow banning by nick in adddition to hostmask.
+    # [_channel_] The channel to ban the user from.
+    # [_hostmask_] A hostmask representing the user we're banning.
+    def ban(channel, hostmask)
+      send_raw("MODE #{channel} +b #{hostmask}")
+    end
+    
+    # Send a message to a channel or a private message to a user.
+    #
+    #   # Send the message "Hello!" to the channel #perkele.
+    #   send_message('#perkele', 'Hello!')
+    #   
+    #   # Send a private message to Jibbler that says "Hi!"
+    #   send_message('Jibbler', 'Hi!')
+    # [_target_] The channel or user nick to send to.
+    # [_message_] The message to send.
+    def send_message(target, message)
+      send_raw("PRIVMSG #{target} :#{message}")
+    end
+    
+    alias :message :send_message
+    alias :msg :send_message
+    alias :pm :send_message
+    
+    # Send an action to a channel or user.
+    # [_target_] The channel or user to send to.
+    # [_action_] The action to send.
+    def send_action(target, action)
+      send_ctcp(target, "ACTION #{action}")
+    end
+    
+    alias :action :send_action
+    
+    # send is a convenience combination of send_message and
+    # send_action. If _message_ begins with "/me ", Cereal sends
+    # an ACTION to _target_. Otherwise, a regular message is sent.
+    # [_target_] The channel or user to send to.
+    # [_message_] The message to send. If _message_ begins with
+    #             "/me ", an ACTION is sent.
+    def send(target, message)
+      if message =~ /^\/me (.*)$/
+        send_action(target, $~[1])
+      else
+        send_message(target, message)
+      end
+    end
+    
+    # Send a notice to a channel or user.
+    # [_target_] The channel or user to send to.
+    # [_notice_] The notice to send.
+    def send_notice(target, notice)
+      send_raw("NOTICE #{target} :#{notice}")
+    end
+    
+    alias :notice :send_notice
+    
+    # Send a CTCP (client-to-client protocol) command to a channel
+    # or user. Examples of such commands are <code>PING <number></code>,
+    # +FINGER+, +VERSION+, etc.
+    #
+    #   # Request the version of the user DeadEd
+    #   send_ctcp('DeadEd', 'VERSION')
+    # [_target_] The channel or user to send the CTCP message to.
+    # [_command_] The CTCP command to send.
+    def send_ctcp(target, command)
+      send_raw("PRIVMSG #{target} :\1#{command}\1")
+    end
+    
+    alias :ctcp :send_ctcp
+    
+    # Change the current nick of the bot. If offline, this method will set
+    # the nick or nicks the bot will try to use upon a connection attempt.
+    # If connected, this method will attempt to change the current nick of
+    # the bot. #nick will return the new nick after the bot receives
+    # confirmation of a successful nick change from the IRC server.
+    #
+    # [_new_nick_] The new nick to use. Can be a String or an Array of
+    #              Strings. If passed an Array, the bot will try each nick
+    #              in order from first to last until it finds a nick that
+    #              is not in use.
+    def nick=(new_nick)
+      if connected?
+        new_nick = new_nick.shift.to_s if new_nick.is_a?(Array)
+        send_raw("NICK #{new_nick}")
+      else
+        @nick = new_nick
+      end
+    end
+    
+    alias :change_nick :nick=
+    
+    # Used by Cereal::Connection to change @nick after we've received a confirmation
+    # that our requested nick has been assigned to us.
+    # [_confirmed_nick_] The nick that has been assigned to us.
+    def confirm_nick(confirmed_nick)
+      @nick = confirmed_nick
+      @connection.temp_nick = confirmed_nick
+    end
+    
+    # Returns _true_ if the bot is currently connected to a server, and _false_
+    # if otherwise (even if the bot is currently negotiating a connection).
+    def connected?
+      @connection && @connection.state == Cereal::Connection::STATE_CONNECTED
+    end
+    
+    # Send raw data to the IRC server.
+    # [_data_] The data to send to the server.
+    def send_raw(data)
+      @connection.send_raw(data) if !data.nil?
+    end
+    
+    alias :<< :send_raw
+    
+    def on_action(sender, target, action)
+      
+    end
+    
+    def on_channel_info(channel, user_count, topic)
+      
+    end
+    
+    def on_connect(host)
+      
+    end
+    
+    def on_disconnect
+      
+    end
+    
+    def on_finger(sender, target)
+      send_raw "NOTICE #{sender.nick} :\1FINGER #{@finger}\1"
+    end
+    
+    def on_invite(sender, target, channel)
+      
+    end
+    
+    def on_join(sender, channel)
+      
+    end
+    
+    def on_kick(sender, channel, recipient, reason)
+      
+    end
+    
+    def on_message(sender, target, message)
+      
+    end
+    
+    def on_nick_change(sender, new_nick)
+      
+    end
+    
+    def on_notice(sender, target, notice)
+      
+    end
+    
+    def on_part(sender, channel)
+      
+    end
+    
+    def on_ping(sender, target, ping_value)
+      send_raw("NOTICE #{sender.nick} :\1PING #{ping_value}\1")
+    end
+    
+    def on_private_message(sender, message)
+      
+    end
+    
+    def on_quit(sender, reason)
+      
+    end
+    
+    def on_server_ping(response)
+      @connection.send_data("PONG #{response}")
+    end
+    
+    # Called when we receive a numeric response from the IRC server. Numeric
+    # replies are received in response to commands sent to the server, and are
+    # documented in RFC 2812, Section 5, "Replies".
+    #
+    # For example, we can use this method to discover the topic of a channel
+    # when we join it. If we join the channel ##test which has a topic of
+    # "My spoon is too big" then the _response_ will be <code>"Cereal ##test
+    # :My spoon is too big"</code> with a _code_ of 332 to signify that this
+    # is a topic. (Note that this is just an example, and that overriding
+    # on_topic is an easier way of finding the topic for a channel.)
+    # [_code_] Integer numeric code for the response.
+    # [_response_] Full response string from the IRC server.
+    def on_server_response(code, response)
+      
+    end
+    
+    def on_time(sender, target)
+      send_raw("NOTICE #{sender.nick} :\1TIME #{Time.new}\1")
+    end
+    
+    # Called whenever a user sets the topic of a channel, or when Cereal
+    # joins a new channel and discovers its topic.
+    # [_set_by_] The nick of the user that set the topic.
+    # [_channel_] The channel whose topic has been set or discovered.
+    # [_date_] When the topic was set as a +Time+.
+    # [_topic_] The topic for the channel.
+    # [_changed_] True if the topic has just been changed, false if we're
+    #             simply discovering a new channel's topic.
+    def on_topic(set_by, channel, date, topic, changed)
+      
+    end
+    
+    # Called whenever we receive a line from the IRC server that Cereal
+    # does not recognize.
+    # [_line_] The raw line that was received from the server.
+    def on_unknown(line)
+      
+    end
+    
+    # Called when we receive a user list from the server after joining a
+    # channel.
+    #
+    # After joining a channel, Cereal collects this information
+    # provided by the IRC server and calls this method as soon as it
+    # has the full list.
+    # [_channel_] The name of the channel.
+    # [_users_] An array of User objects residing in _channel_.
+    def on_user_list(channel, users)
+      
+    end
+    
+    # Called whenever we receive a VERSION CTCP request. The default
+    # implementation responds with Cereal's generic version string,
+    # so if you override this method, be sure to either mimic its
+    # functionality or call <code>super(...)</code>.
+    # [_sender_] An OpenStruct object describing the sender of this
+    #            request. See on_message.
+    # [_target_] The target of the VERSION request, be it our nick
+    #            or a channel name.
+    def on_version(sender, target)
+      send_raw("NOTICE #{sender.nick} :\1VERSION #{@version}\1")
+    end
+    
+  end
+  
+  # == Synopsis
+  # An IRC error class.
+  #
+  # == Author
+  # Ross "Raws" Paffett
+  #
+  # == Copyright
+  # Copyright (c) 2009 Ross Paffett. Licensed under the MIT license:
+  # http://www.opensource.org/licenses/mit-license.php
+  class IrcError < StandardError; end
+  
+  # == Synopsis
+  # A NickAlreadyInUseError class. This exception is raised when Cereal
+  # tries to join an IRC server with a nickname (or nicknames) that is
+  # already in use.
+  #
+  # == Author
+  # Ross "Raws" Paffett
+  #
+  # == Copyright
+  # Copyright (c) 2009 Ross Paffett. Licensed under the MIT license:
+  # http://www.opensource.org/licenses/mit-license.php
+  class NickAlreadyInUseError < IrcError; end
+end

data/lib/connection.rb

@@ -0,0 +1,404 @@
+module Cereal
+
+  # == Synopsis
+  # Cereal::Connection represents a connection to an IRC server. It
+  # is used internally by Cereal::Bot, and you never need to touch it
+  # to use Cereal. Each instance of Cereal::Bot has an attached
+  # Cereal::Connection instance that it communicates with the IRC
+  # server via.
+  #
+  # See the documentation for EventMachine::Connection for more detail.
+  #
+  # == Author
+  # Ross "Raws" Paffett
+  #
+  # == Copyright
+  # Copyright (c) 2009 Ross Paffett. Licensed under the MIT license:
+  # http://www.opensource.org/licenses/mit-license.php
+  class Connection < EventMachine::Connection
+  
+    STATE_DISCONNECTED, STATE_CONNECTING, STATE_CONNECTED = 0, 1, 2
+  
+    attr_reader :state, :channels
+    attr_accessor :temp_nick
+  
+    def initialize(args)
+      # Our parent Cereal::Bot
+      @bot = args[:bot]
+    
+      # Current state of this connection
+      @state = Cereal::Connection::STATE_DISCONNECTED
+    
+      # Details about the server we last connected to
+      @host = nil
+      @password = args[:password]
+    
+      # Hash of channels that is used to remember which users are
+      # in which channels
+      @channels = {}
+    
+      # Hash to temporarily hold channel topics on RPL_TOPIC until
+      # we receive more information on RPL_TOPICINFO
+      @topics = {}
+    
+      # A thread which is responsible for sending messages to the IRC
+      # server in a controlled manner. Its queue prevents a flood of
+      # messages from causing the bot to be kicked from a channel or server.
+      @output_queue = Queue.new
+      @output_thread = Thread.new do
+        while true
+          sleep @bot.message_delay
+          send_data(@output_queue.deq)
+        end
+      end
+      
+      # A string buffer to hold incomplete lines (lines not ending in \r\n)
+      # that we receive from the server.
+      @incomplete_line_buffer = ''
+    end
+  
+    # Send raw data to the IRC server immediately. A trailing newline
+    # is added automatically.
+    # [_data_] The data to send.
+    def send_data(data)
+      return if data.nil? || @state == Cereal::Connection::STATE_DISCONNECTED
+      super(data + "\r\n")
+      @bot.log(">>>#{data}")
+    end
+  
+    # Send raw data to the IRC server through the output queue. Messages
+    # are sent every _n_ seconds, where _n_ is <code>@bot.message_delay</code>.
+    # To bypass the output queue, use send_data.
+    def send_raw(data)
+      @output_queue.enq(data)
+    end
+  
+    # Called upon receiving one or more lines of data from the IRC server.
+    # handle_line is called for each received line of data.
+    # [_data_] The received data.
+    def receive_data(data)
+      data.each_line do |line|
+        if line[-2,2] != "\r\n"
+          @incomplete_line_buffer << line
+        else
+          line = @incomplete_line_buffer + line
+          @bot.log(line)
+          handle_line(line)
+          @incomplete_line_buffer = ''
+        end
+      end
+    end
+  
+    # Called upon successfully establishing a socket connection to the IRC
+    # server. Sends initial messages to the server in an attempt to register
+    # a valid client connection.
+    def post_init
+      # Attempt to register connection with server
+      @state = Cereal::Connection::STATE_CONNECTING
+      send_data("PASS #{@password}") if !@password.nil?
+      bot_nick = @bot.nick
+      @temp_nick = 'CerealBot'
+      if bot_nick.is_a? Array
+        @temp_nick = bot_nick.shift
+      else
+        @temp_nick = bot_nick
+      end
+      send_data("NICK #{@temp_nick}")
+      send_data("USER #{@bot.login} 0 * :#{@bot.name}")
+    end
+  
+    # Called whenever the connection is closed, whether intentional or not.
+    def unbind
+      @state = Cereal::Connection::STATE_DISCONNECTED
+      @bot.on_disconnect
+    end
+  
+    private
+  
+    # Handle one line of data received from the IRC server. This is probably a
+    # good method to look through if you are a) a masochist, b) a maintainer of
+    # this code or c) stark raving mad.
+    #
+    # Note that if you answer B, you are automatically qualified as both A and C.
+    def handle_line(line)
+      GC.start
+      
+      # If this is a PING from the server, respond and return immediately
+      if line =~ /^PING /
+        @bot.on_server_ping(line[5..-1])
+        return
+      end
+    
+      line.chomp!
+    
+      if @state == Cereal::Connection::STATE_CONNECTING && line =~ /^:\S* (\d{3}) (\S+) (\S*).*$/
+        # We're in the process of connecting
+        code = $~[1].to_i
+        if code == 004
+          # We're connected to the server, joy
+          @state = Cereal::Connection::STATE_CONNECTED
+          @temp_nick = $~[2]
+          @host = $~[3]
+          @bot.confirm_nick(@temp_nick)
+          @bot.on_connect(@host)
+        elsif code == 433
+          # Some bellend is already using our nick
+          if @bot.nick.is_a?(Array) && !@bot.nick.empty?
+            @temp_nick = @bot.nick.shift
+            send_data("NICK #{@temp_nick}")
+          else
+            close_connection
+            raise IrcError, "Nickname(s) already in use."
+          end
+        elsif code >= 400 && code <= 599
+          # Error message of some sort
+          @state = Cereal::Connection::STATE_DISCONNECTED
+          close_connection
+          raise IrcError, "Could not log in to IRC server. (#{line})"
+        end
+      elsif @state == Cereal::Connection::STATE_CONNECTED
+        # We're already connected; handle normal commands
+        tokens = line.split
+        if tokens.size < 2
+          # We don't know what this line means
+          @bot.on_unknown(line)
+          return
+        end
+      
+        sender = OpenStruct.new
+        sender.raw = tokens[0]
+        command = tokens[1] ? tokens[1] : ''
+        target = nil
+      
+        if sender.raw =~ /^:(\S+)!(\S+)@(\S+)$/
+          # Sender is probably a human (hostmask)
+          sender.nick, sender.login, sender.hostname = $~[1], $~[2], $~[3]
+        elsif sender.raw =~ /^:\S+$/
+          # Message is, presumably, a server response
+          if tokens.size < 3
+            # Message must contain command and parameters; we don't know
+            # what this line means
+            @bot.on_unknown(line)
+            return
+          end
+        
+          if command =~ /^\d+$/
+            # Command is a numeric server response
+            response = line[line.index(command, sender.raw.length)+4..-1]
+            command = command.to_i
+          
+            if command == 322 && response =~ /([#&]\S+) (\d+) :(.*)/
+              # RPL_LIST: bit of information about a channel
+              channel = $~[1]
+              user_count = $~[2].to_i
+              topic = $~[3]
+              @bot.on_channel_info(channel, user_count, topic)
+            elsif command == 332 && response =~ /([#&]\S+) :(.*)/
+              # RPL_TOPIC: topic of channel we've just joined
+              channel = $~[1]
+              topic = $~[2]
+              @topics[channel] = topic
+            elsif command == 333 && response =~ /([#&]\S+) (\S+) (\S+)/
+              # RPL_TOPICINFO: more topic info of channel we've just joined
+              channel = $~[1]
+              topic = @topics.delete(channel)
+              return if topic.nil?
+              set_by = $~[2]
+              date = Time.at($~[3].to_i)
+              @bot.on_topic(set_by, channel, date, topic, false)
+            elsif command == 353 && response =~ /([=*@]) ([#&]\S+) :(.*)/
+              # RPL_NAMREPLY: list of nicks in a channel we've just joined
+              channel = $~[2]
+              nicks = $~[3].split
+              nicks.each do |str|
+                add_user(Cereal::User.new($~[1], $~[2]), channel) if str =~ /^([@+]{0,2})(\S+)$/
+              end
+            elsif command == 366 && response =~ /([#&]\S+) :End of NAMES list$/
+              # RPL_ENDOFNAMES: we've got the full list of users in a channel
+              # we've just joined
+              channel = $~[1]
+              users = @channels[channel]
+              @bot.on_user_list(channel, users)
+            end
+          
+            @bot.on_server_response(command, response)
+          
+            return
+          else
+            # This is not a server response; must be a nick without a login
+            # and hostname, or perhaps a NOTICE, etc. from the server
+            sender.nick = sender.raw
+            target = command
+          end
+        end
+      
+        return if !command || !sender.nick
+      
+        command.upcase!
+        sender.nick.slice!(0) if sender.nick[0,1] == ':'
+        target = tokens[2] if !target
+        target.slice!(0) if target[0,1] == ':'
+      
+        # Check for CTCP requests
+        if command == 'PRIVMSG' && line.index(":\1") && line.index(":\1") > 0 && line[-1,1] == "\1"
+          request = line[line.index(":\1")+2..-2]
+        
+          case
+          when request == "VERSION"
+            @bot.on_version(sender, target)
+          when request =~ /^ACTION/
+            @bot.on_action(sender, target, request[7..-1])
+          when request =~ /^PING/
+            @bot.on_ping(sender, target, request[5..-1])
+          when request == "TIME"
+            @bot.on_time(sender, target)
+          when request == "FINGER"
+            @bot.on_finger(sender, target)
+          when (tokens = request.split).size >= 5 && tokens[0] == "DCC"
+            # TODO Handle DCC requests -- for now, unknown line
+            @bot.on_unknown(line)
+          else
+            # Unknown CTCP message
+            @bot.on_unknown(line)
+          end
+        elsif command == 'PRIVMSG' && target =~ /^[#&].*$/
+          # Normal message to a channel
+          @bot.on_message(sender, target, line[line.index(' :')+2..-1])
+        elsif command == 'PRIVMSG'
+          # Private message to us
+          @bot.on_private_message(sender, line[line.index(' :')+2..-1])
+        elsif command == 'JOIN'
+          # Someone's joined a channel
+          add_user(sender.nick, target)
+          @bot.on_join(sender, target)
+        elsif command == 'PART'
+          # Someone's parted a channel
+          remove_user(sender.nick, target)
+          remove_channel(target) if sender.nick == @bot.nick
+          @bot.on_part(sender, target)
+        elsif command == 'NICK'
+          # Someone's changed their nick
+          rename_user(sender.nick, target)
+          # Update our nick if it was us that changed
+          @bot.confirm_nick(target) if sender.nick == @temp_nick
+          @bot.on_nick_change(sender, target)
+        elsif command == 'NOTICE'
+          # Someone is sending a notice
+          @bot.on_notice(sender, target, line[line.index(' :')+2..-1])
+        elsif command == 'QUIT'    
+          @bot.on_quit(sender, line[line.index(' :')+2..-1])
+          # Someone's quit from the server
+          if sender.nick == @nick
+            remove_all_channels
+          else
+            remove_user(sender.nick)
+          end
+        elsif command == 'KICK'
+          # Someone's been kicked from a channel
+          recipient = tokens[3]
+          remove_channel(target) if recipient == @nick
+          remove_user(recipient, target)
+          @bot.on_kick(sender, target, recipient, line[line.index(' :')+2..-1])
+        elsif command == 'MODE'
+          # Someone's changed the mode on a channel or user
+          mode = line[line.index(target, 2)+target.length+1..-1]
+          mode.slice!(0) if mode[0,1] == ':'
+          process_mode(sender, target, mode)
+        elsif command == 'TOPIC'
+          # Someone's changed a channel's topic
+          @bot.on_topic(sender.nick, target, Time.new, line[line.index(' :')+2..-1], true)
+        elsif command == 'INVITE'
+          # Someone's inviting someone else to a channel
+          @bot.on_invite(sender, target, tokens[3])
+        end
+      end
+    end
+  
+    # Called when the mode of a channel or user is set. Calls the
+    # appropriate on_op, on_deop, etc methods before handing the event
+    # over to @bot.on_mode.
+    def process_mode(sender, target, mode)
+      if target =~ /^[#&]/
+        # A channel's mode is being changed
+        # TODO Implement this
+      else
+        # A user's mode is being changed
+        # TODO Implement this, too
+      end
+    end
+  
+    # Add a user to the specified channel we know about. Overwrite any
+    # existing entry.
+    def add_user(user, channel)
+      user = Cereal::User.new('', user.to_s) if !user.is_a? Cereal::User
+    
+      channel.downcase!
+      users = @channels.fetch(channel) { |channel| @channels[channel] = {} }
+      users[user] = user
+    end
+  
+    # Remove user from the specified channel or all channels we know about.
+    def remove_user(user, channel=nil)
+      user = Cereal::User.new('', user.to_s) if !user.is_a? Cereal::User
+    
+      if channel
+        channel.downcase!
+        users = @channels.fetch(channel) { |channel| @channels[channel] = {} }
+        users.delete(user)
+      else
+        @channels.each { |users| users.delete(user) }
+      end
+    end
+  
+    # Rename a user if they appear in any of our known channels.
+    def rename_user(old_nick, new_nick)
+      old_user = Cereal::User.new('', old_nick)
+      @channels.each do |channel,users|
+        user = users[old_user]
+        user.nick = new_nick if user
+      end
+    end
+  
+    # Change a user's mode (prefix). Valid values for +mode_change+ include:
+    # ["+@+"] add op and voice
+    # ["+@"] add op
+    # ["++"] add voice
+    # ["-+"] remove voice
+    # ["-@"] remove op
+    # ["-@+"] remove op and voice
+    def change_user_mode(nick, channel, mode_change)
+      channel.downcase!
+      users = @channels.fetch(channel) { |channel| @channels[channel] = {} }
+      user = users[Cereal::User.new('', nick)]
+      if user
+        case mode_change
+        when '+@+'
+          user.op(true)
+          user.voice(true)
+        when '+@'
+          user.op(true)
+        when '++'
+          user.voice(true)
+        when '-+'
+          user.voice(false)
+        when '-@'
+          user.op(false)
+        when '-@+'
+          user.op(false)
+          user.voice(false)
+        end
+      end
+    end
+  
+    # Remove a channel from our known channels.
+    def remove_channel(channel)
+      @channels.delete(channel.downcase)
+    end
+  
+    # Clear all known channels.
+    def remove_all_channels
+      @channels = {}
+    end
+  end
+
+end

data/lib/user.rb

@@ -0,0 +1,98 @@
+module Cereal
+
+  # == Synopsis
+  # Cereal::User Represents a user in an IRC channel. This class is
+  # used by Cereal::Connection and Cereal::Bot to keep track of who is
+  # in each channel the bot currenty occupies. You may receive an array
+  # of Users if you request a list of users in a channel from the bot.
+  #
+  # <code>@lower_nick</code> is set on initialization (or when
+  # <code>@nick</code> is changed) and is simply a <code>downcase</code>d
+  # version of <code>@nick</code>, stored as an instance variable for
+  # performance reasons.
+  #
+  # == Author
+  # Ross "Raws" Paffett
+  #
+  # == Copyright
+  # Copyright (c) 2009 Ross Paffett. Licensed under the MIT license:
+  # http://www.opensource.org/licenses/mit-license.php
+  class User
+  
+    include Comparable
+  
+    attr_reader :prefix, :nick, :lower_nick
+  
+    # Constructs a User object with a known prefix and nick.
+    def initialize(prefix, nick)
+      @prefix = prefix.strip
+      @nick = nick.strip
+      @lower_nick = @nick.downcase
+    end
+  
+    # Returns whether or not this user is an operator.
+    def op?
+      !@prefix.index('@').nil?
+    end
+  
+    # Sets whether or not this user is an operator.
+    def op(is_op)
+      if is_op
+        @prefix = voice? ? '@+' : '@'
+      else
+        @prefix = voice? ? '+' : ''
+      end
+    end
+  
+    # Returns whether or not this user has voice.
+    def voice?
+      !@prefix.index('+').nil?
+    end
+  
+    # Sets whether or not this user has voice.
+    def voice(has_voice)
+      if has_voice
+        @prefix = op? ? '@+' : '+'
+      else
+        @prefix = op? ? '@' : ''
+      end
+    end
+  
+    # Returns the nick of the user with their prefix,
+    # if any, attached.
+    #
+    #   u = Cereal::User.new('+', 'Monty')
+    #   u.to_s => "+Monty"
+    def to_s
+      @prefix + @nick
+    end
+  
+    # Set this user's nick.
+    def nick=(new_nick)
+      @nick = new_nick.strip
+      @lower_nick = @nick.downcase
+    end
+  
+    # Returns true as in ==.
+    def eql?(other)
+      self == other
+    end
+  
+    # Returns the hash of this User object.
+    def hash
+      @lower_nick.hash
+    end
+  
+    # Returns the result of calling <=> on lowercased nicks.
+    # This is useful for sorting lists of Users.
+    def <=>(other)
+      if other.is_a? Cereal::User
+        other.lower_nick <=> @lower_nick
+      else
+        other.to_s.downcase! <=> @lower_nick
+      end
+    end
+  
+  end
+
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: cereal
+version: !ruby/object:Gem::Version 
+  version: 0.1.8
+platform: ruby
+authors: 
+- Ross Paffett
+- Jon R.
+- Brian S
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-01 15:51:42 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.12.2
+    version: 
+description: Cereal provides an event-based IRC connection framework built on EventMachine and inspired by PircBot.
+email: nobody@inparticul.ar
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/cereal.rb
+- lib/connection.rb
+- lib/user.rb
+- CHANGES
+- MIT-LICENSE
+- Rakefile
+- README
+- TODO
+has_rdoc: false
+homepage: http://cerealbot.org/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Event-based IRC connection framework.
+test_files: []
+