net-yail 1.2.0 → 1.2.1

data/CHANGELOG

@@ -34,3 +34,14 @@
 * Fixed logger's handler to not call the channel logging code on private message
 * Figured it's about time for a new gem, 1.2.0.  Change to join handler breaks
   existing code in a minor way - don't forget to fix your handlers!
+
+2008-07-22:
+* Added a bunch of new output APIs and corresponding outgoing handlers
+* Auto-support for server password with new arg to constructor
+* Moved TODO stuff into a separate file outside the gem's evil influence!
+
+2008-07-??:
+* Fixed up a bunch of code to add a bit more stability for dead sockets and
+  such.
+* IRCBot can now properly reconnect when the socket does end up dying.
+* Bumped version to 1.2.1.  Probably a good time to release another gem.

data/README

@@ -56,8 +56,7 @@ Features of YAIL:
   for the most basic working examples.
 
 I still have a lot to do, though.  The output API is definitely not fully
-fleshed out - there are many commands I haven't yet built a shortcut for, such
-as KICK or TOPIC.  I believe that the library is also missing a lot for people
+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)

data/lib/net/yail.rb

@@ -9,21 +9,6 @@ require 'net/yail/magic_events'
 require 'net/yail/default_events'
 require 'net/yail/output_api'
 
-# TODO:
-# * Extract all pattern matching into an external file - store both the
-#   pattern and the event handle's symbol.
-# * Build a system to allow numeric events to get sent post-processed data
-#   if it makes sense (converting the text to specific parts instead of all
-#   handlers having to regex it themselves, for instance)
-# * To deal with the required post-handler logic in the output API, and
-#   "nicely" deal with filtering output, it may be better to have a separate
-#   hash of YAIL-required post-handlers.  This would allow all logic to be
-#   done as handlers (makes things more consistent) as well as getting rid of
-#   the funky arg duping on a per-API-method basis (putting the auto-dupe back
-#   in the handle method)
-# * Handle this:
-#   (14:45.25) +++INCOMING: :Nerdmaster!xxx@yyyy INVITE botname :#channel_name
-
 # If a thread crashes, I want the app to die.  My threads are persistent, not
 # temporary.
 Thread.abort_on_exception = true
@@ -82,10 +67,14 @@ module Net
 #
 # Generally speaking, you won't need these very often, but they're here for
 # the edge cases all the same.  Note that the socket output cannot be skipped
-# (see Return value from events below), so this is truly just to allow
+# (see "Return value from events" below), so this is truly just to allow
 # modifying things before they go out (filtering speech, converting or
 # stripping markup, etc) or just general stats-type logic.
 #
+# Note that in all cases below, the client is *about* to perform an action.
+# Text can be filtered, things can be logged, but keep in mind that the action
+# has not yet happened.
+#
 # Events:
 # * :outgoing_begin_connection(username, address, realname) - called when the
 #   start_listening method has set up all threading and such.  Default behavior
@@ -111,6 +100,21 @@ module Net
 # * :outgoing_nick(new_nick) - The client is about to change nickname
 # * :outgoing_user(username, myaddress, address, realname) - We're about to
 #   send a USER command.
+# * :outgoing_pass(password) - The client is about to send a password to the
+#   server via PASS.
+# * :outgoing_oper(user, password) - The client is about to request ops from
+#   the server via OPER.
+# * :outgoing_topic(channel, new_topic) - If new_topic is blank (nil or ''),
+#   the client is requesting the channel's topic, otherwise setting it.
+# * :outgoing_names(channel) - Client is requesting a list of names in the
+#   given channel, or all channels and names if channel is blank.
+# * :outgoing_list(channel, server) - Client is querying channel information.
+#   I honestly don't know what server is for from RFC, but asking for a
+#   specific channel gives just data on that channel.
+# * :outgoing_invite(nick, channel) - Client is sending an INVITE message to
+#   nick for channel.
+# * :outgoing_kick(nick, channel, comment) - Client is about to kick the user
+#   from the channel with an optional comment.
 #
 # Note that a single output call can hit multiple handlers, so you must plan
 # carefully.  A call to act() will hit the act handler, then ctcp (since act
@@ -221,7 +225,7 @@ class YAIL
     :me,                # Nickname on the IRC server
     :registered,        # If true, we've been welcomed
     :nicknames,         # Array of nicknames to try when logging on to server
-    :dead_socket,       # True if we have no data after a read operation
+    :dead_socket,       # True if @socket.eof? or read/connect fail
     :socket             # TCPSocket instance
   )
   attr_accessor(
@@ -248,6 +252,8 @@ class YAIL
   # * <tt>:throttle_seconds</tt>: Seconds between a cycle of privmsg sends.
   #   Defaults to 1.  One "cycle" is defined as sending one line of output to
   #   *all* targets that have output buffered.
+  # * <tt>:server_password</tt>: Very optional.  If set, this is the password
+  #   sent out to the server before USER and NICK messages.
   def initialize(options = {})
     @me                 = ''
     @nicknames          = options[:nicknames]
@@ -259,6 +265,7 @@ class YAIL
     @silent             = options[:silent] || false
     @loud               = options[:loud] || false
     @throttle_seconds   = options[:throttle_seconds] || 1
+    @password           = options[:server_password]
 
     # Read in map of event numbers and names.  Yes, I stole this event map
     # file from RubyIRC and made very minor changes....  They stole it from
@@ -266,12 +273,17 @@ class YAIL
     eventmap = "#{File.dirname(__FILE__)}/yail/eventmap.yml"
     @event_number_lookup = File.open(eventmap) { |file| YAML::load(file) }.invert
 
-    # Build our socket
-    @socket = TCPSocket.new(@address, @port)
-
     # We're not dead... yet...
     @dead_socket = false
 
+    # Build our socket - if something goes wrong, it's immediately a dead socket.
+    begin
+      @socket = TCPSocket.new(@address, @port)
+    rescue StandardError => boom
+      report "+++ERROR: Unable to open socket connection in Net::YAIL.initialize: #{boom.inspect}"
+      @dead_socket = true
+    end
+
     # Shared resources for threads to try and coordinate....  I know very
     # little about thread safety, so this stuff may be a terrible disaster.
     # Please send me better approaches if you are less stupid than I.
@@ -294,6 +306,9 @@ class YAIL
     # We don't want to spawn an extra listener
     return if Thread === @ioloop_thread
 
+    # Don't listen if socket is dead
+    return if @dead_socket
+
     # 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
@@ -312,10 +327,10 @@ class YAIL
   # regarding threads.  Please help me if you know how to make this system
   # better.  DEAR LORD HELP ME IF YOU CAN!
   def stop_listening
-    @ioloop_thread.terminate
-    @input_processor.terminate
-    @privmsg_processor.terminate
+    # Kill all threads if they're really threads
+    [@ioloop_thread, @input_processor, @privmsg_processor].each {|thread| thread.terminate if Thread === thread}
 
+    # Just for safety, set everything to nil
     @ioloop_thread = nil
     @input_processor = nil
     @privmsg_processor = nil
@@ -326,10 +341,14 @@ class YAIL
   # Reads incoming data - should only be called by io_loop, and only when
   # we've already ensured that data is, in fact, available.
   def read_incoming_data
-    line = @socket.gets
+    begin
+      line = @socket.gets
+    rescue StandardError => boom
+      @dead_socket = true
+      report "+++ERROR in read_incoming_data -> @socket.gets: #{boom.inspect}"
+    end
 
-    # If we have no data, the socket closed.  Nothing to do but set a
-    # status and return
+    # If we somehow got no data here, the socket is closed.  Run away!!!
     if !line
       @dead_socket = true
       return
@@ -352,6 +371,10 @@ class YAIL
     while true
       # if no data is coming in, don't block the socket!
       read_incoming_data if Kernel.select([@socket], nil, nil, 0)
+
+      # Check for dead socket
+      @dead_socket = true if @socket.eof?
+
       sleep 0.05
     end
   end

data/lib/net/yail/IRCBot.rb

@@ -80,6 +80,12 @@ class IRCBot
 
   # Enters the socket's listening loop(s)
   def start_listening
+    # If socket's already dead (probably couldn't connect to server), don't
+    # try to listen!
+    if @irc.dead_socket
+      $stderr.puts "Dead socket, can't start listening!"
+    end
+
     @irc.start_listening
   end
 
@@ -90,7 +96,7 @@ class IRCBot
   # processing.
   def irc_loop
     while true
-      until @irc.dead_socket || @irc.socket.eof?
+      until @irc.dead_socket
         sleep 15
         @irc.handle(:irc_loop)
         Thread.pass

data/lib/net/yail/default_events.rb

@@ -185,12 +185,13 @@ module Defaults
     report "*MOTD* End of MOTD"
   end
 
-  # We dun connected to a server!  Just sends user info and nick.  This isn't
-  # quite "essential" to a working IRC app, but this data *must* be sent at
-  # some point, so be careful before skipping this handler.
+  # 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 skipping this handler.
   def out_begin_connection(username, address, realname)
-    user username, '0.0.0.0', address, realname
-    nick @nicknames[0]
+    pass(@password) if @password
+    user(username, '0.0.0.0', address, realname)
+    nick(@nicknames[0])
   end
 
   # Incoming invitation

data/lib/net/yail/output_api.rb

@@ -18,6 +18,13 @@ module Net
 # 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.
 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
@@ -31,7 +38,7 @@ module IRCOutputAPI
   # 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, or ctcp.
+  # 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
@@ -183,6 +190,8 @@ module IRCOutputAPI
     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
@@ -195,6 +204,87 @@ module IRCOutputAPI
     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
+
+    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
+
+    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
+    server = server.dup
+
+    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
+
+    handle(:outgoing_invite, nick, channel)
+    raw "INVITE #{nick} #{channel}"
+  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
+
+    handle(:outgoing_kick, nick, channel, comment)
+    output = "KICK #{channel} #{nick}"
+    output += " :#{comment}" unless comment.to_s.empty?
+    raw output
+  end
+
 end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: net-yail
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors: 
 - Jeremy Echols
@@ -9,7 +9,7 @@ autorequire: net/yail
 bindir: bin
 cert_chain: []
 
-date: 2008-07-17 00:00:00 -07:00
+date: 2008-08-01 00:00:00 -07:00
 default_executable: 
 dependencies: []