net-yail 1.3.5 → 1.4.0

data/YAIL-RDOC

@@ -0,0 +1,51 @@
+github page: http://github.com/Nerdmaster/ruby-irc-yail
+
+Latest stable release's documentation is always at http://ruby-irc-yail.nerdbucket.com/
+
+Net::YAIL is a library built for dealing with IRC communications in Ruby.
+This is a project I've been building for about three years, based
+originally on the very messy initial release of IRCSocket (back when I first
+started, that was the only halfway-decent IRC lib I found).  I've put a lot
+of time and effort into cleaning it up to make it better for my own uses,
+and now it's almost entirely my code.
+
+Some credit should also be given to Ruby-IRC, as I stole its eventmap.yml
+file with very minor modifications.
+
+This library may not be useful to everybody (or anybody other than myself,
+for that matter), and Ruby-IRC or another lib may work for your situation
+far better than this thing will, but the general design I built here has
+just felt more natural to me than the other libraries I've looked at since
+I started my project.
+
+=Example Usage
+
+For the nitty-gritty, you can see all this stuff in the Net::YAIL page, as
+well as more complete documentation about the system.  For a complete bot,
+check out the IRCBot source code.  Below is just a very simple example:
+
+    require 'rubygems'
+    require 'net/yail'
+
+    irc = Net::YAIL.new(
+      :address    => 'irc.someplace.co.uk',
+      :username   => 'Frakking Bot',
+      :realname   => 'John Botfrakker',
+      :nicknames  => ['bot1', 'bot2', 'bot3']
+    )
+
+    # Register a proc handler
+    irc.prepend_handler :incoming_welcome, proc {|text, args|
+      irc.join('#foo')
+      return false
+    }
+
+    # Register a block
+    irc.prepend_handler(:incoming_invite) {|full, user, channel| irc.join(channel) }
+
+    # Loops forever here until CTRL+C is hit.
+    irc.start_listening!
+
+Now we've built a simple IRC listener that will connect to a (probably
+invalid) network, identify itself, and sit around waiting for the welcome
+message.  After this has occurred, we join a channel and return false.

data/examples/simple/dumbbot.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'net/yail'
+require 'getopt/long'
+
+# User specifies channel and nick
+opt = Getopt::Long.getopts(
+  ['--network',  Getopt::REQUIRED],
+  ['--nick', Getopt::REQUIRED],
+  ['--loud', Getopt::BOOLEAN]
+)
+
+irc = Net::YAIL.new(
+  :address    => opt['network'],
+  :username   => 'Frakking Bot',
+  :realname   => 'John Botfrakker',
+  :nicknames  => [opt['nick']],
+  :loud       => opt['loud']
+)
+
+# Register handlers
+irc.prepend_handler(:incoming_welcome) {|text, args| irc.join('#bots') }
+irc.prepend_handler(:incoming_invite) {|full, user, channel| irc.join(channel) }
+
+# Start the bot and enjoy the endless loop
+irc.start_listening!

data/lib/net/yail.rb

@@ -9,8 +9,11 @@ require 'net/yail/magic_events'
 require 'net/yail/default_events'
 require 'net/yail/output_api'
 
+# This tells us our version info.
+require 'net/yail/yail-version'
+
 # Finally, a real class to include!
-require 'net/yail/message_parser.rb'
+require 'net/yail/event'
 
 # If a thread crashes, I want the app to die.  My threads are persistent, not
 # temporary.
@@ -40,18 +43,19 @@ module Net
 #
 # Current list of incoming events and the parameters sent to the handler:
 # * :incoming_any(raw) - "global" handler that catches all events and may
-#   modify their data as necessary before the real handler is hit.  This
+#   modify their data as necessary before the real handler is hit.  This should
 #   only be used in cases where it's necessary to grab a lot of events that
 #   also need to be processed elsewhere, such as doing input filtering for
 #   all events that have a "text" element.  Note that returning true from
 #   this handler will still break the entire chain of event handling.
 # * :incoming_msg(fullactor, actor, target, text) - Normal message from actor to target
 # * :incoming_act(fullactor, actor, target, text) - CTCP "action" (emote) from actor to target
-# * :incoming_invite(fullactor, actor, target, text) - INVITE to target channel from actor
+# * :incoming_invite(fullactor, actor, target) - INVITE to target channel from actor
 # * :incoming_ctcp(fullactor, actor, target, text) - CTCP other than "action" from actor to target
 # * :incoming_ctcpreply(fullactor, actor, target, text) - CTCP NOTICE from actor to target
 # * :incoming_notice(fullactor, actor, target, text) - other NOTICE from actor to target
 # * :incoming_mode(fullactor, actor, target, modes, objects) - actor sets modes on objects in target channel
+# * :incoming_topic_change(fullactor, actor, channel, text) - actor sets channel topic to given text string
 # * :incoming_join(fullactor, actor, target) - actor joins target channel
 # * :incoming_part(fullactor, actor, target, text) - actor leaves target with message in text
 # * :incoming_kick(fullactor, actor, target, object, text) - actor kicked object from target with reason 'text'
@@ -230,8 +234,6 @@ class YAIL
   include Net::IRCEvents::Defaults
   include Net::IRCOutputAPI
 
-  VERSION = '1.3.5'
-
   attr_reader(
     :me,                # Nickname on the IRC server
     :registered,        # If true, we've been welcomed
@@ -322,6 +324,14 @@ class YAIL
     # Don't listen if socket is dead
     return if @dead_socket
 
+    # Exit a bit more gracefully than just crashing out - allow any :outgoing_quit filters to run,
+    # and even give the server a second to clean up before we fry the connection
+    #
+    # TODO: perhaps this should be in a callback so user can override TERM/INT handling
+    quithandler = lambda { quit('Terminated by user'); sleep 1; stop_listening; exit }
+    trap("INT", quithandler)
+    trap("TERM", quithandler)
+
     # Build forced / magic logic - welcome setting @me, ping response, etc.
     # Since we do these here, nobody can skip them and they're always first.
     setup_magic_handlers
@@ -336,17 +346,36 @@ class YAIL
     handle(:outgoing_begin_connection, @username, @address, @realname)
   end
 
+  # This starts the connection, threading, etc. as start_listening, but *forces* the user into
+  # and endless loop.  Great for a simplistic bot, but probably not universally desired.
+  def start_listening!
+    start_listening
+    while !@dead_socket
+      # This is more for CPU savings than actually needing a delay - CPU spikes if we never sleep
+      sleep 0.05
+    end
+  end
+
   # Kills and clears all threads.  See note above about my lack of knowledge
   # regarding threads.  Please help me if you know how to make this system
   # better.  DEAR LORD HELP ME IF YOU CAN!
   def stop_listening
-    # Kill all threads if they're really threads
-    [@ioloop_thread, @input_processor, @privmsg_processor].each {|thread| thread.terminate if Thread === thread}
+    return unless Thread === @ioloop_thread
 
-    # Just for safety, set everything to nil
-    @ioloop_thread = nil
-    @input_processor = nil
-    @privmsg_processor = nil
+    # Do thread-ending in a new thread or else we're liable to kill the
+    # thread that's called this method
+    Thread.new do
+      # Kill all threads if they're really threads
+      [@ioloop_thread, @input_processor, @privmsg_processor].each {|thread| thread.terminate if Thread === thread}
+
+      @socket.close
+      @socket = nil
+      @dead_socket = true
+
+      @ioloop_thread = nil
+      @input_processor = nil
+      @privmsg_processor = nil
+    end
   end
 
   private
@@ -382,7 +411,7 @@ class YAIL
   # This should be called from a thread only!  Does nothing but listens
   # forever for incoming data, and calling handlers due to this listening
   def io_loop
-    while true
+    loop do
       # if no data is coming in, don't block the socket!
       read_incoming_data if Kernel.select([@socket], nil, nil, 0)
 
@@ -397,7 +426,7 @@ class YAIL
   # whenever the @input_buffer var has any.
   def process_input_loop
     lines = nil
-    while true
+    loop do
       # Only synchronize long enough to copy and clear the input buffer.
       @input_buffer_mutex.synchronize do
         lines = @input_buffer.dup
@@ -456,7 +485,7 @@ class YAIL
   # Our final thread loop - grabs the first privmsg for each target and
   # sends it on its way.
   def process_privmsg_loop
-    while true
+    loop do
       check_privmsg_output if @next_message_time <= Time.now && !@privmsg_buffer.empty?
 
       sleep 0.05
@@ -474,63 +503,69 @@ class YAIL
       end
     end
 
-    # Use the exciting new parser
-    msg = Net::YAIL::MessageParser.new(line)
+    # Use the exciting new-new parser
+    event = Net::YAIL::IncomingEvent.parse(line)
+
+    # Partial conversion to using events - we still have a horrible case statement, but
+    # we're at least using the event object.  Slightly less hacky than before.
 
-    # In the legacy system, there are never situations where we want the params
-    # separated into array elements.  So we convert them here, since so many
-    # handlers require a param or two followed by "everything else".
-    params = msg.params.dup
-    param1 = params.shift
-    other1 = params.join(' ') || ''
-    param2 = params.shift
-    other2 = params.join(' ') || ''
+    # Except for this - we still have to handle numerics the crappy way until we build the proper
+    # dispatching of events
+    event = event.parent if event.parent && :incoming_numeric == event.parent.type
 
-    case msg.command
+    case event.type
       # Ping is important to handle quickly, so it comes first.
-      when 'PING'
-        handle(:incoming_ping, msg.params.first)
-      when /^\d{3}$/
-        handle_numeric(msg.command.to_i, msg.prefix, msg.nick, param1, other1)
-      when 'INVITE'
-        handle(:incoming_invite, msg.prefix, msg.nick, msg.params.last)
-
-      # This can encompass three possible messages, so further refining happens here - the last param
-      # is always the message itself, so we look for patterns there.
-      when 'PRIVMSG'
-        case msg.params.last
-          when /^\001ACTION (.+?)\001$/
-            handle(:incoming_act, msg.prefix, msg.nick, msg.params.first, $1)
-          when /^\001(.+?)\001$/
-            handle(:incoming_ctcp, msg.prefix, msg.nick, msg.params.first, $1)
-          else
-            handle(:incoming_msg, msg.prefix, msg.nick, param1, other1)
-        end
+      when :incoming_ping
+        handle(event.type, event.text)
 
-      # This can encompass two possible messages, again based on final param
-      when 'NOTICE'
-        case msg.params.last
-          when /^\001(.+?)\001$/
-            handle(:incoming_ctcpreply, msg.prefix, msg.nick, msg.params.first, $1)
-          else
-            handle(:incoming_notice, msg.prefix, msg.nick, param1, other1)
-        end
+      when :incoming_numeric
+        # Lovely - I passed in a "nick" - which, according to spec, is NEVER part of a numeric reply
+        handle_numeric(event.numeric, event.servername, nil, event.target, event.text)
+
+      when :incoming_invite
+        handle(event.type, event.fullname, event.nick, event.channel)
+
+      # Fortunately, the legacy handler for all five "message" types is the same!
+      when :incoming_msg, :incoming_ctcp, :incoming_act, :incoming_notice, :incoming_ctcpreply
+        # Legacy handling requires merger of target and channel....
+        target = event.target if event.pm?
+        target = event.channel if !target
+
+        # Notices come from server sometimes, so... another merger for legacy fun!
+        nick = event.server? ? '' : event.nick
+        handle(event.type, event.from, nick, target, event.text)
+
+      # This is a bit painful for right now - just use some hacks to make it work semi-nicely,
+      # but let's not put hacks into the core Event object.  Modes need reworking soon anyway.
+      #
+      # NOTE: text is currently the mode settings ('+b', for instance) - very bad.  TODO: FIX FIX FIX!
+      when :incoming_mode
+        # Modes can come from the server, so legacy system again regularly sent nil data....
+        nick = event.server? ? '' : event.nick
+        handle(event.type, event.from, nick, event.channel, event.text, event.targets.join(' '))
+
+      when :incoming_topic_change
+        handle(event.type, event.fullname, event.nick, event.channel, event.text)
 
-      when 'MODE'
-        handle(:incoming_mode, msg.prefix, msg.nick, param1, param2, other2)
-      when 'JOIN'
-        handle(:incoming_join, msg.prefix, msg.nick, param1)
-      when 'PART'
-        handle(:incoming_part, msg.prefix, msg.nick, param1, other1)
-      when 'KICK'
-        handle(:incoming_kick, msg.prefix, msg.nick, param1, param2, other2)
-      when 'QUIT'
-        handle(:incoming_quit, msg.prefix, msg.nick, param1)
-      when 'NICK'
-        handle(:incoming_nick, msg.prefix, msg.nick, param1)
+      when :incoming_join
+        handle(event.type, event.fullname, event.nick, event.channel)
+
+      when :incoming_part
+        handle(event.type, event.fullname, event.nick, event.channel, event.text)
+
+      when :incoming_kick
+        handle(event.type, event.fullname, event.nick, event.channel, event.target, event.text)
+
+      when :incoming_quit
+        handle(event.type, event.fullname, event.nick, event.text)
+
+      when :incoming_nick
+        handle(event.type, event.fullname, event.nick, event.text)
 
       # Unknown line!
       else
+        # This should really never happen, so reporting is forced here for now
+        report('Unknown line: %s!' % line.inspect)
         handle(:incoming_miscellany, line)
     end
   end
@@ -542,9 +577,14 @@ class YAIL
   public
   # Event handler hook.  Kinda hacky.  Calls your event(s) before the default
   # event.  Default stuff will happen if your handler doesn't return true.
-  def prepend_handler(event, *procs)
+  def prepend_handler(event, *procs, &block)
     raise "Cannot change handlers while threads are listening!" if @ioloop_thread
 
+    # Allow blocks as well as procs
+    if block_given?
+      procs.push(block)
+    end
+
     # See if this is a word for a numeric - only applies to incoming events
     if (event.to_s =~ /^incoming_(.*)$/)
       number = @event_number_lookup[$1].to_i

data/lib/net/yail/default_events.rb

@@ -114,6 +114,9 @@ module Defaults
   # user or try again in 20 minutes or something.  Note that we only fail
   # when the adapter hasn't gotten logged in yet - an attempt at changing
   # nick after registration (welcome message) just generates a report.
+  #
+  # TODO: This should really not even be here.  Client should have full control over whether or not
+  # they want this.  Base IRC bot class should have this, but not the core YAIL lib.
   def _nicknameinuse(text, args)
     text =~ /^(\S+)/
     report "Nickname #{$1} is already in use."
@@ -153,6 +156,8 @@ module Defaults
   end
 
   # Names line
+  #
+  # TODO: Either store this data silently or ditch this code - this verbosity doesn't belong in a core lib
   def _namreply(text, args)
     text =~ /^(@|\*|=) (\S+) :?(.+)$/
     channeltype = {'@' => 'Secret', '*' => 'Private', '=' => 'Normal'}[$1]

data/lib/net/yail/event.rb

@@ -0,0 +1,285 @@
+require 'net/yail/message_parser.rb'
+
+module Net
+class YAIL
+
+  # Base event class for stuff shared by any type of event.  Note that :type and :handled
+  # apply to *all* events, so they're explicitly defined here.
+  class BaseEvent
+    attr_reader :type, :handled
+
+    # Creates an event object and sets up some sane defaults for common elements
+    def initialize()
+      @handled = false
+      @type = nil
+    end
+
+    # Sets this event as having been handled (i.e., no further handling should occur)
+    def handle; @handled = true; end
+
+    # Cheesy shortcut to @handled in "boolean" form
+    def handled?; return @handled; end
+  end
+
+  # The outgoing event class - outgoing events haven't got much in
+  # common, so this class is primarily to facilitate the new system.
+  class OutgoingEvent < BaseEvent
+    # Outgoing events in our system are always :outgoing_xxx
+    def type
+      return :"outgoing_#{@type.to_s}"
+    end
+  end
+
+  # This is the incoming event class.  For all situations where the server
+  # sent us some kind of event, this class handles all the data.
+  #
+  # All events will have a :raw attribute that stores the exact text sent from
+  # the IRC server.  Other possible pieces of data are as follows:
+  # * fullname: Rarely needed, full text of origin of an action
+  # * nick: Nickname of originator of an event
+  # * channel: Where applicable, the name of the channel in which the event
+  #   happened.
+  # * text: Actual message/emote/notice/etc
+  # * target: User targeted for various commands - PRIVMSG/NOTICE recipient, KICK victim, etc
+  # * pm?: Set to true if the event is a "private" event (not sent to the
+  #   channel).  Useful primarily for message types of events (PRIVMSG).
+  #
+  # To more easily call the right user event, we store each event type and its "parent" where it
+  # makes sense.  This ensures that a user currently handling :incoming_ctcp won't be totally
+  # screwed when we add in :incoming_userinfo and such.  Top-level handlers aren't in here, which
+  # is vital to avoid trying to hack around numerics (not to mention a bunch of fairly useless
+  # data)
+  #
+  # Look at the source for specifics of which IRC events set up what data.  Or try to parse the
+  # lovely RFCs....
+  #
+  # For convenience, the event stores its MessageParser object so users can access raw data as
+  # necessary (for numeric messages, this is often useful)
+  class IncomingEvent < BaseEvent
+    attr_reader :raw, :msg
+    private_class_method :new
+
+    # Sets up data and accessors
+    def initialize(data = {})
+      super()
+
+      # Don't modify incoming element!
+      @data = data.dup
+      @raw = @data.delete(:raw)
+      @msg = @data.delete(:msg)
+      @type = @data.delete(:type)
+
+      # Give useful accessors in a hacky but fun way!  I can't decide if I prefer the pain of
+      # using method_missing or the pain of not knowing how to do this without a string eval....
+      for key in @data.keys
+        key = key.to_s
+        self.instance_eval("def #{key}; return @data[:#{key}]; end")
+      end
+    end
+
+    # Helps us debug
+    def to_s
+      return super().gsub('IncomingEvent', "IncomingEvent[#{@type.to_s}]")
+    end
+
+    # Incoming events in our system are always :incoming_xxx
+    def type; return :"incoming_#{@type.to_s}"; end
+
+    # Effectively our event "factory" - uses Net::YAIL::MessageParser and returns an event
+    # object - usually just one, but TODO: some lines actually contain multiple messages.  When
+    # EventManager or similar is implemented, we'll just register events and this will be a non-issue
+    def self.parse(line)
+      # Parse with MessageParser to get raw IRC info
+      raw = line.dup
+      msg = Net::YAIL::MessageParser.new(line)
+      data = { :raw => raw, :msg => msg, :parent => nil }
+
+      # Not all messages from the server identify themselves as such, so we just assume it's from
+      # the server unless we explicitly see a nick
+      data[:server?] = true
+
+      # Sane defaults for most messages
+      if msg.servername
+        data[:from] = data[:servername] = msg.servername
+      elsif msg.prefix && msg.nick
+        data[:from] = data[:fullname] = msg.prefix
+        data[:nick] = msg.nick
+        data[:server?] = false
+      end
+
+      case msg.command
+        when 'ERROR'
+          data[:type] = :error
+          data[:text] = msg.params.last
+          event = new(data)
+
+        when 'PING'
+          data[:type] = :ping
+          data[:text] = msg.params.last
+          event = new(data)
+
+        when 'TOPIC'
+          data[:type] = :topic_change
+          data[:channel] = msg.params.first
+          data[:text] = msg.params.last
+          event = new(data)
+
+        when /^\d{3}$/
+          # Get base event for the "numeric" type - so many of these exist, and so few are likely
+          # to be handled directly.  Sadly, some hackery has to happen here to make "text" backward-
+          # compatible since old YAIL auto-joined all parameters into one string.
+          data[:type] = :numeric
+          params = msg.params.dup
+          data[:target] = params.shift
+          data[:parameters] = params
+          data[:text] = params.join(' ')
+          data[:numeric] = msg.command.to_i
+          event = new(data)
+
+          # Create child event for the specific numeric
+          data[:type] = msg.command.to_sym
+          data[:parent] = event
+          event = new(data)
+
+        when 'INVITE'
+          data[:type] = :invite
+          data[:channel] = msg.params.last
+
+          # This should always be us, but still worth capturing just in case
+          data[:target] = msg.params.first
+          event = new(data)
+  
+        # This can encompass three possible messages, so further refining happens here - the last param
+        # is always the message itself, so we look for patterns there.
+        when 'PRIVMSG'
+          event = privmsg_events(msg, data)
+  
+        # This can encompass two possible messages, again based on final param
+        when 'NOTICE'
+          event = notice_events(msg, data)
+  
+        when 'MODE'
+          event = mode_events(msg, data)
+
+        when 'JOIN'
+          data[:type] = :join
+          data[:channel] = msg.params.last
+          event = new(data)
+
+        when 'PART'
+          data[:type] = :part
+          data[:channel] = msg.params.first
+          data[:text] = msg.params.last
+          event = new(data)
+
+        when 'KICK'
+          data[:type] = :kick
+          data[:channel] = msg.params[0]
+          data[:target] = msg.params[1]
+          data[:text] = msg.params[2]
+          event = new(data)
+
+        when 'QUIT'
+          data[:type] = :quit
+          data[:text] = msg.params.first
+          event = new(data)
+
+        when 'NICK'
+          data[:type] = :nick
+          data[:text] = msg.params.first
+          event = new(data)
+  
+        # Unknown line!  If this library is complete, we should *never* see this situation occur,
+        # so it'll be up to the caller to decide what to do.
+        else
+          data[:type] = :unknown
+          event = new(data)
+      end
+
+      return event
+    end
+
+    protected
+
+    # Parses a MODE to its events - basic, backward-compatible :mode event for now, but
+    # TODO: eventually get set up for multiple atomic mode messages (need event manager first)
+    def self.mode_events(msg, data)
+      data[:type]     = :mode
+      data[:channel]  = msg.params.shift
+      data[:text]     = msg.params.shift
+      data[:targets]  = msg.params
+      event = new(data)
+    end
+
+    # Parses basic data for the "message" constructs: PRIVMSG and NOTICE
+    def self.parse_message_data(msg, data)
+      # Defaults so all messages have a fairly standard interface
+      data[:pm?] = false
+      data[:target] = nil
+      data[:channel] = msg.params.first
+
+      # If this isn't a channel message, set up PM data - keep channel, just set it to nil so the
+      # API is consistent
+      unless msg.params.first =~ /^[!&#+]/
+        data[:channel] = nil
+        data[:pm?] = true
+        data[:target] = msg.params.first
+      end
+    end
+
+    # Parses a PRIVMSG to its events - CTCP stuff needs parents, ACT stuff needs two-parent
+    # hierarchy
+    def self.privmsg_events(msg, data)
+      # Parse common elements
+      parse_message_data(msg, data)
+
+      # Get base event
+      data[:type] = :msg
+      data[:text] = msg.params.last
+      event = new(data)
+
+      # Is this CTCP?
+      if event.text =~ /^\001(.+?)\001$/
+        data[:type] = :ctcp
+        data[:text] = $1
+        data[:parent] = event
+        
+        event = new(data)
+      end
+
+      # CTCP action?
+      if :ctcp == data[:type] && event.text =~ /^ACTION (.+)$/
+        data[:type] = :act
+        data[:text] = $1
+        data[:parent] = event
+
+        event = new(data)
+      end
+
+      return event
+    end
+
+    # Parses a NOTICE to its events - CTCP replies come through here
+    def self.notice_events(msg, data)
+      # Parse common elements
+      parse_message_data(msg, data)
+
+      # Get base event
+      data[:type] = :notice
+      data[:text] = msg.params.last
+      event = new(data)
+
+      if event.text =~ /^\001(.+?)\001$/
+        data[:type] = :ctcp_reply
+        data[:text] = $1
+        data[:parent] = event
+
+        event = new(data)
+      end
+
+      return event
+    end
+
+  end
+end
+end

data/lib/net/yail/magic_events.rb

@@ -42,7 +42,7 @@ module Magic
   def magic_nick(fullactor, actor, nickname)
     # Reset name if it's me
     if actor.downcase == @me.downcase
-      @me = nickname
+      @me = nickname.dup
     end
 
     # Allow user-defined events (and/or reporting)

data/lib/net/yail/message_parser.rb

@@ -1,3 +1,6 @@
+# Net::YAIL's solution to the amazing lack of *useful* IRC message parsers.  So far as I know,
+# this will parse any message coming from an RFC-compliant IRC server.
+
 module Net
 class YAIL
 
@@ -57,7 +60,8 @@ class MessageParser
       # separate the trailing arg as it can contain nearly any character. And
       # finally, we split the "middle" args on space.
       arglist = matches[6].sub(/^ +/, '')
-      (middle_args, trailing_arg) = arglist.split(/ *:/, 2)
+      arglist.sub!(/^:/, ' :')
+      (middle_args, trailing_arg) = arglist.split(/ +:/, 2)
       @params.push(middle_args.split(/ +/), trailing_arg)
       @params.compact!
       @params.flatten!

data/lib/net/yail/output_api.rb

@@ -32,7 +32,7 @@ module IRCOutputAPI
   # speaking, that is.
   def raw(line, report = true)
     @socket.puts line
-    report "bot: '#{line}'" if report
+    report "bot: #{line.inspect}" if report
   end
 
   # Calls :outgoing_privmsg handler, then sends a message (text) out to the

data/lib/net/yail/yail-version.rb

@@ -0,0 +1,5 @@
+module Net
+  class YAIL
+    VERSION = '1.4.0'
+  end
+end

data/tests/net_yail.rb

@@ -1,4 +1,5 @@
 $LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib")
 require 'net/yail'
 require 'net/yail/message_parser'
+require 'net/yail/event'
 puts "VERSION: #{Net::YAIL::VERSION}"

data/tests/tc_event.rb

@@ -0,0 +1,227 @@
+#!/usr/bin/env ruby
+require File.dirname(__FILE__) + '/net_yail'
+require 'test/unit'
+
+# Stolen from tc_message_parser - same tests, different object
+class MessageParserEventTest < Test::Unit::TestCase
+  # Simplest test case, I think
+  def test_ping
+    event = Net::YAIL::IncomingEvent.parse("PING :nerdbucket.com")
+    assert_equal 'nerdbucket.com', event.text
+    assert_equal :incoming_ping, event.type
+    assert !event.respond_to?(:servername)
+    assert !event.respond_to?(:nick)
+    assert !event.respond_to?(:channel)
+    assert !event.respond_to?(:fullname)
+    assert event.server?
+  end
+
+  def test_topic
+    event = Net::YAIL::IncomingEvent.parse(":Dude!dude@nerdbucket.com TOPIC #nerdtalk :31 August 2010 \357\277\275 Foo.")
+    assert_equal :incoming_topic_change, event.type
+    assert_equal 'Dude', event.nick
+    assert_equal "31 August 2010 \357\277\275 Foo.", event.text
+    assert_equal '#nerdtalk', event.channel
+    assert_equal 'Dude!dude@nerdbucket.com', event.fullname
+  end
+
+  # Parsing of PRIVMSG messages
+  def test_messages
+    # Basic test of privmsg-type command
+    event = Net::YAIL::IncomingEvent.parse(':Nerdmaster!jeremy@nerdbucket.com PRIVMSG Nerdminion :Do my bidding!!')
+    assert_nil event.parent
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal 'jeremy', event.msg.user
+    assert_equal 'nerdbucket.com', event.msg.host
+    assert_equal 'Nerdmaster!jeremy@nerdbucket.com', event.fullname
+    assert_equal 'Nerdmaster!jeremy@nerdbucket.com', event.from
+    assert !event.server?
+    assert_equal 'PRIVMSG', event.msg.command
+    assert_equal :incoming_msg, event.type
+    assert_equal 'Nerdminion', event.target
+    assert_equal true, event.pm?
+    assert_equal 'Do my bidding!!', event.text
+
+    # CTCP to user
+    event = Net::YAIL::IncomingEvent.parse(":Nerdmaster!jeremy@nerdbucket.com PRIVMSG Nerdminion :\001FOO is to bar as BAZ is to...?\001")
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal :incoming_ctcp, event.type
+    assert_nil event.channel
+    assert_equal 'Nerdminion', event.target
+    assert_equal true, event.pm?
+    assert_equal 'FOO is to bar as BAZ is to...?', event.text
+    assert_equal :incoming_msg, event.parent.type
+    assert_equal "\001FOO is to bar as BAZ is to...?\001", event.parent.text
+    assert_nil event.parent.parent
+
+    # Action to channel
+    event = Net::YAIL::IncomingEvent.parse(":Nerdmaster!jeremy@nerdbucket.com PRIVMSG #bottest :\001ACTION gives Towelie a joint\001")
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal :incoming_act, event.type
+    assert_equal '#bottest', event.channel
+    assert_equal false, event.pm?
+    assert_equal 'gives Towelie a joint', event.text
+    assert_equal :incoming_ctcp, event.parent.type
+    assert_equal "ACTION gives Towelie a joint", event.parent.text
+    assert_equal :incoming_msg, event.parent.parent.type
+    assert_equal "\001ACTION gives Towelie a joint\001", event.parent.parent.text
+    assert_nil event.parent.parent.parent
+
+    # PM to channel with less common prefix
+    event = Net::YAIL::IncomingEvent.parse(":Nerdmaster!jeremy@nerdbucket.com PRIVMSG !bottest :foo")
+    assert_equal :incoming_msg, event.type
+    assert_equal false, event.pm?
+    assert_equal '!bottest', event.channel
+  end
+
+  # Quick test of a numeric message I've ACTUALLY SEEN!!
+  def test_numeric
+    event = Net::YAIL::IncomingEvent.parse(':nerdbucket.com 266 Nerdmaster :Current global users: 22  Max: 33')
+    assert_equal 'Current global users: 22  Max: 33', event.text
+    assert_equal :incoming_266, event.type
+    assert_equal 'nerdbucket.com', event.servername
+    assert_equal 'nerdbucket.com', event.from
+    assert_equal 'Nerdmaster', event.target
+
+    assert !event.respond_to?(:nick)
+    assert !event.respond_to?(:channel)
+    assert !event.respond_to?(:fullname)
+    assert event.server?
+
+    assert_equal :incoming_numeric, event.parent.type
+    assert_equal 266, event.parent.numeric
+
+    # Numeric with multiple args
+    event = Net::YAIL::IncomingEvent.parse(':someserver.co.uk.fn.bb 366 Towelie #bottest :End of /NAMES list.')
+    assert_equal :incoming_366, event.type
+    assert_equal '#bottest End of /NAMES list.', event.text
+    assert_equal ['#bottest', 'End of /NAMES list.'], event.parameters
+
+    # First param in the message params list should still be nick
+    assert_equal 'Towelie', event.msg.params.first
+  end
+
+  # Test an invite
+  def test_invite
+    event = Net::YAIL::IncomingEvent.parse(':Nerdmaster!jeremy@nerdbucket.com INVITE Nerdminion :#nerd-talk')
+    assert_equal '#nerd-talk', event.channel
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal 'Nerdminion', event.target
+  end
+
+  # Test a user joining message
+  def test_join
+    event = Net::YAIL::IncomingEvent.parse(':Nerdminion!minion@nerdbucket.com JOIN :#nerd-talk')
+    assert_equal '#nerd-talk', event.channel
+    assert_equal 'Nerdminion', event.nick
+    assert_equal :incoming_join, event.type
+  end
+
+  def test_part
+    event = Net::YAIL::IncomingEvent.parse(':Nerdminion!minion@nerdbucket.com PART #nerd-talk :No, YOU GO TO HELL')
+    assert_equal '#nerd-talk', event.channel
+    assert_equal 'Nerdminion', event.nick
+    assert_equal 'No, YOU GO TO HELL', event.text
+    assert_equal :incoming_part, event.type
+  end
+
+  def test_kick
+    event = Net::YAIL::IncomingEvent.parse(%q|:Nerdmaster!jeremy@nerdbucket.com KICK #nerd-talk Nerdminion :You can't quit!  You're FIRED!|)
+    assert_equal '#nerd-talk', event.channel
+    assert_equal 'Nerdminion', event.target
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal :incoming_kick, event.type
+    assert_equal %q|You can't quit!  You're FIRED!|, event.text
+  end
+
+  def test_quit
+    event = Net::YAIL::IncomingEvent.parse(':TheTowel!ce611d7b0@nerdbucket.com QUIT :Bye bye')
+    assert_equal 'TheTowel', event.nick
+    assert_equal :incoming_quit, event.type
+    assert_equal 'Bye bye', event.text
+  end
+
+  def test_nick
+    # Nick change when nick is "unusual" - this also tests the bug with a single parameter being
+    # treated incorrectly
+    event = Net::YAIL::IncomingEvent.parse(':[|\|1]!~nerdmaste@nerd.nerdbucket.com NICK :Deadnerd')
+    assert_equal '[|\|1]', event.nick
+    assert_equal :incoming_nick, event.type
+    assert_equal 'Deadnerd', event.text
+  end
+
+  # Test some notice stuff
+  def test_notice_and_ctcp_reply
+    event = Net::YAIL::IncomingEvent.parse(":nerdbucket.com NOTICE Nerdminion :You suck.  A lot.")
+    assert_equal 'nerdbucket.com', event.servername
+    assert_equal 'nerdbucket.com', event.from
+    assert event.server?
+    assert_equal :incoming_notice, event.type
+    assert_equal 'Nerdminion', event.target
+    assert !event.respond_to?(:nick)
+    assert !event.respond_to?(:fullname)
+    assert_equal 'You suck.  A lot.', event.text
+
+    # This CTCP message...
+    #     ":Nerdmaster!jeremy@nerdbucket.com PRIVMSG Nerdminion \001USERINFO\001"
+    # ...might yield this response:
+    event = Net::YAIL::IncomingEvent.parse(":Nerdminion!minion@nerdbucket.com NOTICE Nerdmaster :\001USERINFO :Minion of the nerd\001")
+    assert !event.respond_to?(:servername)
+    assert_equal :incoming_ctcp_reply, event.type
+    assert_equal 'Nerdmaster', event.target
+    assert_equal 'Nerdminion', event.nick
+    assert_equal 'Nerdminion!minion@nerdbucket.com', event.fullname
+    assert_equal 'Nerdminion!minion@nerdbucket.com', event.from
+    assert_equal 'USERINFO :Minion of the nerd', event.text
+
+    # Channel-wide notice
+    event = Net::YAIL::IncomingEvent.parse(":Nerdmaster!jeremy@nerdbucket.com NOTICE #channel-ten-news :Tonight's late-breaking story...")
+    assert !event.respond_to?(:servername)
+    assert_equal :incoming_notice, event.type
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal '#channel-ten-news', event.channel
+    assert_nil event.target
+    assert_equal 'Nerdmaster!jeremy@nerdbucket.com', event.fullname
+    assert_equal %q|Tonight's late-breaking story...|, event.text
+  end
+
+  def test_modes
+    event = Net::YAIL::IncomingEvent.parse(":Nerdmaster!jeremy@nerdbucket.com MODE #bots +ob Towelie Doogles!*@*")
+    assert !event.respond_to?(:servername)
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal :incoming_mode, event.type
+    assert_equal '#bots', event.channel
+    assert_equal ['Towelie', 'Doogles!*@*'], event.targets
+    assert_equal '+ob', event.text
+
+    # Newly-created channels do this
+    event = Net::YAIL::IncomingEvent.parse(':nerdbucket.com MODE #bots +nt')
+    assert event.server?
+    assert_equal 'nerdbucket.com', event.servername
+
+    # TODO: Parse modes better!  This case will be interesting, as the "i" is channel-specific.  Useful
+    # parsing would give us something like {'#bots' => '-i', 'Doogles!*@*' => '-b', 'Towelie' => '-v', 'Nerdmaster' => '-v'}
+    event = Net::YAIL::IncomingEvent.parse(":Nerdmaster!jeremy@nerdbucket.com MODE #bots -bivv Doogles!*@* Towelie Nerdmaster")
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal :incoming_mode, event.type
+    assert_equal '#bots', event.channel
+    assert_equal ['Doogles!*@*', 'Towelie', 'Nerdmaster'], event.targets
+    assert_equal '-bivv', event.text
+
+    event = Net::YAIL::IncomingEvent.parse(":Nerdmaster!jeremy@nerdbucket.com MODE #bots +m")
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal :incoming_mode, event.type
+    assert_equal '#bots', event.channel
+    assert_equal [], event.targets
+    assert_equal '+m', event.text
+
+    # TODO: This is even worse than above - this is a pretty specific message (setting channel key
+    # to 'foo'), but has to be parsed in a pretty absurd way to get that info.
+    event = Net::YAIL::IncomingEvent.parse(":Nerdmaster!jeremy@nerdbucket.com MODE #bots +k foo")
+    assert_equal 'Nerdmaster', event.nick
+    assert_equal :incoming_mode, event.type
+    assert_equal '#bots', event.channel
+    assert_equal ['foo'], event.targets
+    assert_equal '+k', event.text
+  end
+end

data/tests/tc_message_parser.rb

@@ -2,7 +2,7 @@
 require File.dirname(__FILE__) + '/net_yail'
 require 'test/unit'
 
-class MessageParserText < Test::Unit::TestCase
+class MessageParserTest < Test::Unit::TestCase
   # Very simple parsing of easy strings
   def test_parse_basic
     # Basic test of privmsg-type command
@@ -26,6 +26,15 @@ class MessageParserText < Test::Unit::TestCase
     assert_equal 'arg2', msg.params[1]
     assert_equal 'final :trailing :arg, --fd9823', msg.params[2]
 
+    # Server command of some type - no actual final arg
+    msg = Net::YAIL::MessageParser.new(':nerdbucket.com SERVERCOMMAND arg1:finaltrailingarg')
+    assert_equal 'nerdbucket.com', msg.servername
+    assert_nil msg.user
+    assert_nil msg.nick
+    assert_nil msg.host
+    assert_equal 'nerdbucket.com', msg.prefix
+    assert_equal 'arg1:finaltrailingarg', msg.params[0]
+
     # WTF?  Well, IRC spec says it's valid
     msg = Net::YAIL::MessageParser.new('MAGICFUNKYFRESHCMD arg1 arg2')
     assert_nil msg.servername
@@ -34,11 +43,11 @@ class MessageParserText < Test::Unit::TestCase
     assert_equal 'arg2', msg.params[1]
 
     # Action
-    msg = Net::YAIL::MessageParser.new(':Nerdmaster!jeremy@nerdbucket.com PRIVMSG #bottest :\001ACTION gives Towelie a joint\001')
+    msg = Net::YAIL::MessageParser.new(":Nerdmaster!jeremy@nerdbucket.com PRIVMSG #bottest :\001ACTION gives Towelie a joint\001")
     assert_equal 'Nerdmaster', msg.nick
     assert_equal 'PRIVMSG', msg.command
     assert_equal '#bottest', msg.params.first
-    assert_equal '\001ACTION gives Towelie a joint\001', msg.params.last
+    assert_equal "\001ACTION gives Towelie a joint\001", msg.params.last
 
     # Bot sets mode
     msg = Net::YAIL::MessageParser.new(':Towelie!~x2e521146@towelie.foo.bar MODE Towelie :+i')
@@ -67,5 +76,13 @@ class MessageParserText < Test::Unit::TestCase
     assert_equal '[|\|1]!~nerdmaste@nerd.nerdbucket.com', msg.prefix
     assert_equal 'Deadnerd', msg.params.shift
     assert_equal 0, msg.params.length
+
+    # Annoying topic change
+    msg = Net::YAIL::MessageParser.new(":Dude!dude@nerdbucket.com TOPIC #nerdtalk :31 August 2010 \357\277\275 Foo.")
+    assert_equal 'TOPIC', msg.command
+    assert_equal 'Dude', msg.nick
+    assert_equal "31 August 2010 \357\277\275 Foo.", msg.params.last
+    assert_equal '#nerdtalk', msg.params.first
+    assert_equal 'Dude!dude@nerdbucket.com', msg.prefix
   end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
-  - 3
-  - 5
-  version: 1.3.5
+  - 4
+  - 0
+  version: 1.4.0
 platform: ruby
 authors: 
 - Jeremy Echols
@@ -14,7 +14,7 @@ autorequire: net/yail
 bindir: bin
 cert_chain: []
 
-date: 2010-08-09 00:00:00 -04:00
+date: 2010-09-02 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -25,8 +25,9 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+- YAIL-RDOC
 files: 
+- examples/simple/dumbbot.rb
 - examples/logger/logger_bot.rb
 - examples/logger/default.yml
 - examples/logger/run.rb
@@ -37,10 +38,12 @@ files:
 - lib/net/yail/message_parser.rb
 - lib/net/yail/default_events.rb
 - lib/net/yail/output_api.rb
-- lib/net/yail/event_manager.rb
+- lib/net/yail/event.rb
+- lib/net/yail/yail-version.rb
 - tests/net_yail.rb
 - tests/tc_message_parser.rb
-- README
+- tests/tc_event.rb
+- YAIL-RDOC
 has_rdoc: true
 homepage: http://ruby-irc-yail.nerdbucket.com/
 licenses: []
@@ -48,7 +51,7 @@ licenses: []
 post_install_message: 
 rdoc_options: 
 - --main
-- README
+- YAIL-RDOC
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -77,3 +80,4 @@ summary: "Yet Another IRC Library: wrapper for IRC communications in Ruby."
 test_files: 
 - tests/net_yail.rb
 - tests/tc_message_parser.rb
+- tests/tc_event.rb

data/README

@@ -1,67 +0,0 @@
-Rubyforge page: http://rubyforge.org/projects/ruby-irc-yail
-
-*Want to jump straight to the examples instead of reading this lame "about the project" doc?  Just click on Net::YAIL !*
-
-Net::YAIL is a library built for dealing with IRC communications in Ruby.
-This is a project I've been building for about three years, based
-originally on the very messy initial release of IRCSocket (back when I first
-started, that was the only halfway-decent IRC lib I found).  I've put a lot
-of time and effort into cleaning it up to make it better for my own uses,
-and now it's almost entirely my code.
-
-Some credit should also be given to Ruby-IRC, as I stole its eventmap.yml
-file with very minor modifications.
-
-This library may not be useful to everybody (or anybody other than myself,
-for that matter), and Ruby-IRC or another lib may work for your situation
-far better than this thing will, but the general design I built here has
-just felt more natural to me than the other libraries I've looked at since
-I started my project.
-
-Features of YAIL:
-
-* Allows event handlers to be specified very easily for all known IRC events,
-  and except in a few rare cases one can choose to override the default
-  handling mechanisms.
-* Allows handling outgoing messages, such as when privmsg is called.  The API
-  won't allow you to stop the outgoing message (though I may offer this if
-  people want it), but you can filter data before it's sent out.  This is one
-  thing I didn't see anywhere else.
-* Threads for input and output are persistent.  This is a feature, not a bug.
-  Some may hate this approach, but I'm a total n00b to threads, and it seemed
-  like the way to go, having thread loops responsible for their own piece of
-  the library.  I'd *love* input here if anybody can tell me why this is a bad
-  idea....
-* "Stacked" event handling is possible if you want to provide a very modular
-  framework of your own.  When you prepend a handler, its return determines if
-  the next handler will get called.  This isn't useful for a simple bot most
-  likely, but can have some utility in bigger projects where a single event
-  may need to be dispatched to several handlers.
-* Easy to build a simple bot without subclassing anything.  One gripe I had
-  with IRCSocket was that it was painful to do anything without subclassing
-  and overriding methods.  No need here.
-* Lots of built-in reporting.  You may hate this part, but for a bot, it's
-  really handy to have most incoming data reported on some level.  I may make
-  this optional at some point, but only if people complain, since I haven't
-  yet seen a need to do so....
-* Built-in PRIVMSG buffering!  You can of course choose to not buffer, but by
-  default you cannot send more than one message to a given target (user or
-  channel) more than once per second.  Additionally, this buffering method is
-  ideal for a bot that's trying to be chatty on two channels at once, because
-  buffering is per-target, so queing up 20 lines on <tt>##foo</tt> doesn't mean waiting
-  20 seconds to spit data out to <tt>##bar</tt>.  The one caveat here is that if your
-  app is trying to talk to too many targets at once, the buffering still won't
-  save you from a flood-related server kick.  If this is a problem for others,
-  I'll look into building an even more awesome buffering system.
-* The included IRCBot is a great starting point for building your own bot,
-  but if you want something even simpler, just look at Net::YAIL's documentation
-  for the most basic working examples.
-
-I still have a lot to do, though.  The output API is definitely not fully
-fleshed out.  I believe that the library is also missing a lot for people
-who just have a different approach than me, since this was purely designed for
-my own benefit, and then released almost exclusively to piss off the people
-whose work I stole to get where I'm at today.  (Just kiddin', Pope)
-
-This code is released under the MIT license.  I hear it's all the rage with
-the kids these days.