net-yail 1.4.6 → 1.5.1

data/lib/net/yail/legacy_events.rb

@@ -0,0 +1,214 @@
+module Net
+module IRCEvents
+
+# All code here is going to be removed completely at some point, and only exists here to serve the 1.x branch
+# (and remind me how awful the old system really was)
+module LegacyEvents
+
+  # DEPRECATED
+  #
+  # 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, &block)
+    raise "Cannot change handlers while threads are listening!" if @ioloop_thread
+
+    @log.warn "[DEPRECATED] - Net::YAIL#prepend_handler is deprecated as of 1.5.0 - please see documentation on the new " +
+        "event handling model methods - http://ruby-irc-yail.nerdbucket.com/"
+
+    # 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
+      event = :"incoming_numeric_#{number}" if number > 0
+    end
+
+    @legacy_handlers[event] ||= Array.new
+    until procs.empty?
+      @legacy_handlers[event].unshift(procs.pop)
+    end
+  end
+
+  # Handles the given event (if it's in the @legacy_handlers array) with the
+  # arguments specified.
+  #
+  # The @legacy_handlers must be a hash where key = event to handle and value is
+  # a Proc object (via Class.method(:name) or just proc {...}).
+  # This should be fine if you're setting up handlers with the prepend_handler
+  # method, but if you get "clever," you're on your own.
+  def handle(event, *arguments)
+    # Don't bother with anything if there are no handlers registered.
+    return false unless Array === @legacy_handlers[event]
+
+    @log.debug "+++EVENT HANDLER: Handling event #{event} via #{@legacy_handlers[event].inspect}:"
+
+    # Call all hooks in order until one breaks the chain.  For incoming
+    # events, we want something to break the chain or else it'll likely
+    # hit a reporter.  For outgoing events, we tend to report them anyway,
+    # so no need to worry about ending the chain except when the bot wants
+    # to take full control over them.
+    result = false
+    for handler in @legacy_handlers[event]
+      result = handler.call(*arguments)
+      break if result == true
+    end
+
+    # Let the new system deal with legacy handlers that wanted to end the chain
+    return result
+  end
+
+  # Since numerics are so many and so varied, this method will auto-fallback
+  # to a simple report if no handler was defined.
+  def handle_numeric(number, fullactor, actor, target, message)
+    # All numerics share the same args, and rarely care about anything but
+    # message, so let's make it easier by passing a hash instead of a list
+    args = {:fullactor => fullactor, :actor => actor, :target => target}
+    base_event = :"incoming_numeric_#{number}"
+    if Array === @legacy_handlers[base_event]
+      return handle(base_event, message, args)
+    else
+      # No handler = report and don't worry about it
+      @log.info "Unknown raw #{number.to_s} from #{fullactor}: #{message}"
+      return false
+    end
+  end
+
+  # Gets some input, sends stuff off to a handler.  Yay.
+  def legacy_process_event(event)
+    # Allow global handler to break the chain, filter the line, whatever.  When we ditch these legacy
+    # events, this code will finally die!
+    if (Net::YAIL::IncomingEvent === event && Array === @legacy_handlers[:incoming_any])
+      for handler in @legacy_handlers[:incoming_any]
+        result = handler.call(event.raw)
+        return true if true == result
+      end
+    end
+
+    # 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.
+
+    # 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 event.type
+      # Ping is important to handle quickly, so it comes first.
+      when :incoming_ping
+        return handle(event.type, event.message)
+
+      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.message)
+
+      when :incoming_invite
+        return 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
+        return handle(event.type, event.from, nick, target, event.message)
+
+      # 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: message 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
+        return handle(event.type, event.from, nick, event.channel, event.message, event.targets.join(' '))
+
+      when :incoming_topic_change
+        return handle(event.type, event.fullname, event.nick, event.channel, event.message)
+
+      when :incoming_join
+        return handle(event.type, event.fullname, event.nick, event.channel)
+
+      when :incoming_part
+        return handle(event.type, event.fullname, event.nick, event.channel, event.message)
+
+      when :incoming_kick
+        return handle(event.type, event.fullname, event.nick, event.channel, event.target, event.message)
+
+      when :incoming_quit
+        return handle(event.type, event.fullname, event.nick, event.message)
+
+      when :incoming_nick
+        return handle(event.type, event.fullname, event.nick, event.message)
+
+      when :incoming_error
+        return handle(event.type, event.message)
+
+      when :outgoing_privmsg, :outgoing_msg, :outgoing_ctcp, :outgoing_act, :outgoing_notice, :outgoing_ctcpreply
+        return handle(event.type, event.target, event.message)
+
+      when :outgoing_mode
+        return handle(event.type, event.target, event.modes, event.objects)
+
+      when :outgoing_join
+        return handle(event.type, event.channel, event.password)
+
+      when :outgoing_part
+        return handle(event.type, event.channel, event.message)
+
+      when :outgoing_quit
+        return handle(event.type, event.message)
+
+      when :outgoing_nick
+        return handle(event.type, event.nick)
+
+      when :outgoing_user
+        return handle(event.type, event.username, event.hostname, event.servername, event.realname)
+
+      when :outgoing_pass
+        return handle(event.type, event.password)
+
+      when :outgoing_oper
+        return handle(event.type, event.user, event.password)
+
+      when :outgoing_topic
+        return handle(event.type, event.channel, event.topic)
+
+      when :outgoing_names
+        return handle(event.type, event.channel)
+
+      when :outgoing_list
+        return handle(event.type, event.channel, event.server)
+
+      when :outgoing_invite
+        return handle(event.type, event.nick, event.channel)
+
+      when :outgoing_kick
+        return handle(event.type, event.nick, event.channel, event.reason)
+
+      when :outgoing_begin_connection
+        return handle(event.type, event.username, event.address, event.realname)
+
+      # Unknown line - if an incoming event, we need to log it as that shouldn't be able to happen,
+      # but we don't want to kill somebody's app for it.  An outgoing event that's part of the
+      # system should NEVER hit this, so we throw an error in that case.  Custom events just get
+      # handled with no arguments, to allow for things like :irc_loop.
+      else
+        case event
+          when Net::YAIL::IncomingEvent
+            @log.warn 'Unknown line: %s!' % event.raw.inspect
+            @log.warn "Please report this to the github repo at https://github.com/Nerdmaster/ruby-irc-yail/issues"
+            return handle(:incoming_miscellany, event.raw)
+          when Net::YAIL::OutgoingEvent
+            raise "Unknown outgoing event: #{event.inspect}"
+          else
+            handle(event.type)
+        end
+    end
+  end
+end
+
+end
+end

data/lib/net/yail/magic_events.rb

@@ -1,52 +1,56 @@
 module Net
 module IRCEvents
 
-# This module contains all the "magic" methods that need to happen regardless
-# of user-defined event hooks and such.
+# This module contains all the "magic" methods that need to happen by default.  User could overwrite
+# some of these, but really really shouldn't.
 module Magic
   private
 
-  # Sets up the magic handlers that must happen no matter what else occurs
-  def setup_magic_handlers
-    prepend_handler :incoming_welcome,          self.method(:magic_welcome)
-    prepend_handler :incoming_ping,             self.method(:magic_ping)
-    prepend_handler :incoming_nick,             self.method(:magic_nick)
+  # We dun connected to a server!  Just sends password (if one is set) and
+  # user/nick.  This isn't quite "essential" to a working IRC app, but this data
+  # *must* be sent at some point, so be careful before clobbering this handler.
+  def out_begin_connection(event)
+    pass(@password) if @password
+    user(event.username, '0.0.0.0', event.address, event.realname)
+    nick(@nicknames[0])
   end
 
   # We were welcomed, so we need to set up initial nickname and set that we
   # registered so nick change failure doesn't cause DEATH!
-  def magic_welcome(text, args)
-    report "#{args[:fullactor]} welcome message: #{text}"
-    if (text =~ /(\S+)!\S+$/)
+  def magic_welcome(event)
+    # TODO: Ditch this call to report - move to report lib if necessary
+    report "#{event.from} welcome message: #{event.message}"
+    if (event.message =~ /(\S+)!\S+$/)
       @me = $1
-    elsif (text =~ /(\S+)$/)
+    elsif (event.message =~ /(\S+)$/)
       @me = $1
     end
 
     @registered = true
     mode @me, 'i'
-
-    # Don't break the chain if user wants their own handler
-    return false
   end
 
-  # Ping must have a PONG even if user wants their own handler
-  def magic_ping(text)
-    @socket.puts "PONG :#{text}"
+  # Ping must have a PONG, though crazy user can handle this her own way if she likes
+  def magic_ping(event); @socket.puts "PONG :#{event.message}"; end
 
-    # Don't break the chain, man
-    return false
+  # If bot changes his name, @me must change - this must be a filter, not the callback!
+  def magic_nick(event)
+    @me = event.message.dup if event.nick.downcase == @me.downcase
   end
 
-  # If bot changes his name, @me must change
-  def magic_nick(fullactor, actor, nickname)
-    # Reset name if it's me
-    if actor.downcase == @me.downcase
-      @me = nickname.dup
-    end
+  # User calls msg, sends a simple message out to the event's target (user or channel)
+  def magic_out_msg(event)
+    privmsg(event.target, event.message)
+  end
+
+  # CTCP
+  def magic_out_ctcp(event)
+    privmsg(event.target, "\001#{event.message}\001")
+  end
 
-    # Allow user-defined events (and/or reporting)
-    return false
+  # CTCP ACTION
+  def magic_out_act(event)
+    privmsg(event.target, "\001ACTION #{event.message}\001")
   end
 
 end

data/lib/net/yail/output_api.rb

@@ -1,290 +1,110 @@
 module Net
 
-# All output APIs live here.  In most cases, an outgoing handler will get a
-# call, but will not be able to stop the socket output since that's sorta
-# an essential part of this whole library.
-#
-# ==Argument Duping
-#
-# Output APIs dup incoming args before sending them off to handlers.  This
-# is a mechanism that I think could be done better, but I can't figure a good
-# way to do it at the moment.  The reason this is necessary is for a specific
-# situation where a bot has an array of response messages, and needs to filter
-# those messages.  A call to "msg(messages[rand(10)])" with a handler on :outgoing_msg
-# that does something like <code>text.gsub!('a', '@')</code> (like a leetspeek
-# filter) shouldn't destroy the original data in the messages array.
-#
-# This could be left up to the programmer, but it seems like something that
-# a library should own - protecting the programmer for having to remember that
-# sort of crap, especially if the app is calling msg, act, ctcp, etc. in
-# various ways from multiple points in the code....
-#
-# ==Apologies, good sirs
-# 
-# If a method exists in this module, and it isn't the +raw+ method, chances
-# are it's got a handler in the form of :outgoing_<method name>.  I am hoping
-# I document all of those in the main Net::YAIL code, but if I miss one, I
-# apologize.
+# This module is responsible for the raw socket output, buffering of all "message" types of
+# events, and exposing the magic to create a new output command + handler.  All output methods
+# are documented in the main Net::YAIL documentation.
 module IRCOutputAPI
   # Spits a raw string out to the server - in case a subclass wants to do
   # something special on *all* output, please make all output go through this
   # method.  Don't use puts manually.  I will kill violaters.  Legally
   # speaking, that is.
-  def raw(line, report = true)
+  def raw(line)
     @socket.puts "#{line}\r\n"
-    report "bot: #{line.inspect}" if report
   end
 
-  # Calls :outgoing_privmsg handler, then sends a message (text) out to the
-  # given channel/user (target), and reports itself with the given string.
-  # This method shouldn't be called directly most of the time - just use msg,
-  # act, ctcp, etc.
-  #
-  # This is sort of the central message output - everything that's based on
-  # PRIVMSG (messages, actions, other ctcp) uses this.  Because these messages
-  # aren't insanely important, we actually buffer them instead of sending
-  # straight out to the channel.  The output thread has to deal with
-  # sending these out.
-  def privmsg(target, text, report_string)
-    # Dup strings so handler can filter safely
-    target = target.dup
-    text = text.dup
-
-    handle(:outgoing_privmsg, target, text)
-
+  # Buffers the given event to be sent out when we are able to send something out to the given
+  # target.  If buffering isn't turned on, the event will be processed in the next loop of outgoing
+  # messages.
+  def buffer_output(event)
     @privmsg_buffer_mutex.synchronize do
-      @privmsg_buffer[target] ||= Array.new
-      @privmsg_buffer[target].push([text, report_string])
+      @privmsg_buffer[event.target] ||= Array.new
+      @privmsg_buffer[event.target].push event
     end
   end
 
-  # Calls :outgoing_msg handler, then privmsg to send the message out.  Could
-  # be used to send any privmsg, but you're betting off using act and ctcp
-  # shortcut methods for those types.  Target is a channel or username, text
+  # Buffers an :outgoing_msg event.  Could be used to send any privmsg, but you're betting off
+  # using act and ctcp shortcut methods for those types.  Target is a channel or username, message
   # is the message.
-  def msg(target, text)
-    # Dup strings so handler can filter safely
-    target = target.dup
-    text = text.dup
-
-    handle(:outgoing_msg, target, text)
-
-    report_string = @log_silent ? '' : "{#{target}} <#{@me}> #{text}"
-    privmsg(target, text, report_string)
-  end
-
-  # Calls :outgoing_ctcp handler, then sends CTCP to target channel or user
-  def ctcp(target, text)
-    # Dup strings so handler can filter safely
-    target = target.dup
-    text = text.dup
-
-    handle(:outgoing_ctcp, target, text)
-
-    report_string = @log_silent ? '' :  "{#{target}}  [#{@me} #{text}]"
-    privmsg(target, "\001#{text}\001", report_string)
+  def msg(target, message)
+    buffer_output Net::YAIL::OutgoingEvent.new(:type => :msg, :target => target, :message => message)
   end
 
-  # Calls :outgoing_act handler, then ctcp to send a CTCP ACTION (text) to
-  # a given user or channel (target)
-  def act(target, text)
-    # Dup strings so handler can filter safely
-    target = target.dup
-    text = text.dup
-
-    handle(:outgoing_act, target, text)
-
-    ctcp(target, "ACTION #{text}")
+  # Buffers an :outgoing_ctcp event.  Target is user or channel, message is message.
+  def ctcp(target, message)
+    buffer_output Net::YAIL::OutgoingEvent.new(:type => :ctcp, :target => target, :message => message)
   end
 
-  # Calls :outgoing_notice handler, then outputs raw NOTICE message
-  def notice(target, text)
-    # Dup strings so handler can filter safely
-    target = target.dup
-    text = text.dup
-
-    handle(:outgoing_notice, target, text)
-
-    report "{#{target}} -#{@me}- #{text}" unless @log_silent
-    raw("NOTICE #{target} :#{text}", false)
+  # Buffers an :outgoing_act event.  Target is user or channel, message is message.
+  def act(target, message)
+    buffer_output Net::YAIL::OutgoingEvent.new(:type => :act, :target => target, :message => message)
   end
 
-  # Calls :outgoing_ctcpreply handler, then uses notice method to send the
-  # CTCP text
-  def ctcpreply(target, text)
-    # Dup strings so handler can filter safely
-    target = target.dup
-    text = text.dup
-
-    handle(:outgoing_ctcpreply, target, text)
-
-    report "{#{target}} [Reply: #{@me} #{text}]" unless @log_silent
-    notice(target, "\001#{text}\001")
-  end
-
-  # Calls :outgoing_mode handler, then mode to set mode(s) on a channel
-  # and possibly specific users (objects).  If modes and objects are blank,
-  # just sends a raw MODE query.
-  def mode(target, modes = '', objects = '')
-    # Dup strings so handler can filter safely
-    target = target.dup
-    modes = modes.dup
-    objects = objects.dup
-
-    handle(:outgoing_mode, target, modes, objects)
-
-    message = "MODE #{target}"
-    message += " #{modes}" unless modes.to_s.empty?
-    message += " #{objects}" unless objects.to_s.empty?
-    raw message
-  end
-
-  # Calls :outgoing_join handler and then raw JOIN message for a given channel
-  def join(target, pass = '')
-    # Dup strings so handler can filter safely
-    target = target.dup
-    pass = pass.dup
-
-    handle(:outgoing_join, target, pass)
-
-    text = "JOIN #{target}"
-    text += " #{pass}" unless pass.empty?
-    raw text
-  end
-
-  # Calls :outgoing_part handler and then raw PART for leaving a given channel
-  # (with an optional message)
-  def part(target, text = '')
-    # Dup strings so handler can filter safely
-    target = target.dup
-    text = text.dup
-
-    handle(:outgoing_part, target, text)
-
-    request = "PART #{target}";
-    request += " :#{text}" unless text.to_s.empty?
-    raw request
-  end
-
-  # Calls :outgoing_quit handler and then raw QUIT message with an optional
-  # reason
-  def quit(text = '')
-    # Dup strings so handler can filter safely
-    text = text.dup
-
-    handle(:outgoing_quit, text)
-
-    request = "QUIT";
-    request += " :#{text}" unless text.to_s.empty?
-    raw request
-  end
-
-  # Calls :outgoing_nick handler and then sends raw NICK message to change
-  # nickname.
-  def nick(new_nick)
-    # Dup strings so handler can filter safely
-    new_nick = new_nick.dup
-
-    handle(:outgoing_nick, new_nick)
-
-    raw "NICK :#{new_nick}"
-  end
-
-  # Identifies ourselves to the server.  Calls :outgoing_user and sends raw
-  # USER command.
-  def user(username, myaddress, address, realname)
-    # Dup strings so handler can filter safely
-    username = username.dup
-    myaddress = myaddress.dup
-    address = address.dup
-    realname = realname.dup
-
-    handle(:outgoing_user, username, myaddress, address, realname)
-
-    raw "USER #{username} #{myaddress} #{address} :#{realname}"
-  end
-
-  # Sends a password to the server.  This *must* be sent before NICK/USER.
-  # Calls :outgoing_pass and sends raw PASS command.
-  def pass(password)
-    # Dupage
-    password = password.dup
-
-    handle(:outgoing_pass, password)
-    raw "PASS #{password}"
-  end
-
-  # Sends an op request.  Calls :outgoing_oper and raw OPER command.
-  def oper(user, password)
-    # Dupage
-    user = user.dup
-    password = password.dup
-
-    handle(:outgoing_oper, user, password)
-    raw "OPER #{user} #{password}"
-  end
-
-  # Gets or sets the topic.  Calls :outgoing_topic and raw TOPIC command
-  def topic(channel, new_topic = nil)
-    # Dup for filter safety in outgoing handler
-    channel = channel.dup
-    new_topic = new_topic.dup unless new_topic.nil?
-
-    handle(:outgoing_topic, channel, new_topic)
-    output = "TOPIC #{channel}"
-    output += " :#{new_topic}" unless new_topic.to_s.empty?
-    raw output
-  end
-
-  # Gets a list of users and channels if channel isn't specified.  If channel
-  # is specified, only shows users in that channel.  Will not show invisible
-  # users or channels.  Calls :outgoing_names and raw NAMES command.
-  def names(channel = nil)
-    channel = channel.dup unless channel.nil?
-
-    handle(:outgoing_names, channel)
-    output = "NAMES"
-    output += " #{channel}" unless channel.to_s.empty?
-    raw output
-  end
-
-  # I don't know what the server param is for, but it's in the RFC.  If
-  # channel is blank, lists all visible, otherwise just lists the channel in
-  # question.  Calls :outgoing_list and raw LIST command.
-  def list(channel = nil, server = nil)
-    channel = channel.dup unless channel.nil?
-    server = server.dup unless server.nil?
-
-    handle(:outgoing_list, channel, server)
-    output = "LIST"
-    output += " #{channel}" if channel
-    output += " #{server}" if server
-    raw output
-  end
-
-  # Invites a user to a channel.  Calls :outgoing_invite and raw INVITE
-  # command.
-  def invite(nick, channel)
-    channel = channel.dup
-    server = server.dup
+  # Creates an output command and its handler.  output_base is a template of the command without
+  # any conditional arguments (for simple commands this is the full template).  args is a list of
+  # argument symbols to determine how the event is built and handled.  If an argument symbol is
+  # followed by a string, that string is conditionally appended to the output in the handler if the
+  # event has data for that argument.
+  #
+  # I hate the hackiness here, but it's so much easier to build the commands and handlers with an
+  # ugly one-liner than manually, and things like define_method seem to fall short with how much
+  # crap this needs to do.
+  def create_command(command, output_base, *opts)
+    event_opts = lambda {|text| text.gsub(/:(\w+)/, '#{event.\1}') }
+
+    output_base = event_opts.call(output_base)
+
+    # Create a list of actual arg symbols and templates for optional args
+    args = []
+    optional_arg_templates = {}
+    last_symbol = nil
+    for opt in opts
+      case opt
+      when Symbol
+        args.push opt
+        last_symbol = opt
+      when String
+        raise ArgumentError.new("create_command optional argument must have an argument symbol preceding them") unless last_symbol
+        optional_arg_templates[last_symbol] = event_opts.call(opt)
+        last_symbol = nil
+      end
+    end
 
-    handle(:outgoing_invite, nick, channel)
-    raw "INVITE #{nick} #{channel}"
-  end
+    # Format strings for command args and event creation
+    event_string = args.collect {|arg| ":#{arg} => #{arg}"}.join(",")
+    event_string = ", #{event_string}" unless event_string.empty?
+    args_string = args.collect {|arg| "#{arg} = ''"}.join(",")
+
+    # Create the command function
+    command_code = %Q|
+      def #{command}(#{args_string})
+        dispatch Net::YAIL::OutgoingEvent.new(:type => #{command.inspect}#{event_string})
+      end
+    |
+    self.class.class_eval command_code
+
+    # Create the handler piece by piece - wow how ugly this is!
+    command_handler = :"magic_out_#{command}"
+    handler_code = %Q|
+      def #{command_handler}(event)
+        output_string = "#{output_base}"
+    |
+    for arg in args
+      if optional_arg_templates[arg]
+        handler_code += %Q|
+          output_string += "#{optional_arg_templates[arg]}" unless event.#{arg}.to_s.empty?
+        |
+      end
+    end
+    handler_code += %Q|
+        raw output_string
+      end
+    |
 
-  # Kicks the given user from the channel with the optional comment.  Calls
-  # :outgoing_kick and issues a raw KICK command.
-  def kick(nick, channel, comment = nil)
-    nick = nick.dup
-    channel = channel.dup
-    comment = comment.dup unless comment.nil?
+    self.class.class_eval handler_code
 
-    handle(:outgoing_kick, nick, channel, comment)
-    output = "KICK #{channel} #{nick}"
-    output += " :#{comment}" unless comment.to_s.empty?
-    raw output
+    # At least setting the callback isn't a giant pile of dumb
+    set_callback :"outgoing_#{command}", self.method(command_handler)
   end
-
 end
 
 end