comboy-autumn 3.1

data/lib/autumn/coder.rb

@@ -0,0 +1,166 @@
+# Defines the Autumn::Coder class and its subclasses, which generate template
+# code for the script/generate utility.
+
+module Autumn
+  
+  # Helper class that generates shell Ruby code. This class knows how to
+  # generate Ruby code for template classes and methods.
+  
+  class Coder # :nodoc:
+    # The generated code string.
+    attr :output
+    
+    # Creates a new instance with an indent level of 0 and an empty output
+    # string.
+    
+    def initialize
+      @indent = 0
+      @output = String.new
+    end
+    
+    # Creates a new class empty class. This method yields another Generator,
+    # which you can populate with the contents of the class, if you wish.
+    # Example:
+    #
+    #  gen.klass("Foo") { |foo| foo.method("bar") }
+    #
+    # produces:
+    #
+    #  class Foo
+    #    def bar
+    #    end
+    #  end
+    
+    def klass(name, superclass=nil)
+      if superclass then
+        self << "class #{name} < #{superclass}"
+      else
+        self << "class #{name}"
+      end
+      
+      if block_given? then
+        generator = self.class.new
+        yield generator
+        indent!
+        self << generator.output
+        unindent!
+      end
+      
+      self << "end"
+      
+      return self
+    end
+    
+    # Creates a new empty method. Any additional parameters are considered to be
+    # the generated method's parameters. They can be symbols/strings (taken to
+    # be the parameter's name), or hashes associating the parameter's name to
+    # its default value.
+    #
+    # This method yields another Generator, which you can populate with the
+    # contents of the method, if you wish. Example:
+    #
+    #  gen.method("test", :required, { :optional => 'default' })
+    #
+    # produces:
+    #
+    #  def test(required, optional="default")
+    #  end
+    
+    def method(name, *params)
+      if params.empty? then
+        self << "def #{name}"
+      else
+        self << "def #{name}(#{parameterize params})"
+      end
+      
+      if block_given? then
+        generator = self.class.new
+        yield generator
+        indent!
+        self << generator.output
+        unindent!
+      end
+      
+      self << "end"
+      
+      return self
+    end
+    
+    # Increases the indent level for all future lines of code appended to this
+    # Generator.
+    
+    def indent!
+      @indent = @indent + 1
+    end
+    
+    # Decreases the indent level for all future lines of code appended to this
+    # Generator.
+    
+    def unindent!
+      @indent = @indent - 1 unless @indent == 0
+    end
+    
+    # Adds a line of code to this Generator, sequentially.
+    
+    def <<(str)
+      str.split(/\n/).each do |line|
+        @output << "#{tab}#{line}\n"
+      end
+    end
+    
+    def doc=(str)
+      doc_lines = str.line_wrap(80 - tab.size - 2).split("\n")
+      doc_lines.map! { |str| "#{tab}# #{str}\n" }
+      @output = doc_lines.join + "\n" + @output
+    end
+    
+    # Appends a blank line to the output.
+    
+    def newline!
+      @output << "\n"
+    end
+    
+    private
+    
+    def parameterize(params)
+      param_strs = Array.new
+      params.each do |param|
+        if param.kind_of? Hash and param.size == 1 then
+          name = param.keys.only
+          default = param.values.only
+          raise ArgumentError, "Invalid parameter #{name.inspect}" unless name.respond_to? :to_s and not name.to_s.empty?
+          param_strs << "#{name.to_s}=#{default.inspect}"
+        elsif param.respond_to? :to_s and not param.to_s.empty? then
+          param_strs << param.to_s
+        else
+          raise ArgumentError, "Invalid parameter #{param.inspect}"
+        end
+      end
+      return param_strs.join(', ')
+    end
+    
+    def tab
+      '  ' * @indent
+    end
+  end
+  
+  # Generates Autumn-specific code templates like leaves and filters.
+  
+  class TemplateCoder < Coder # :nodoc:
+    
+    # Generates an Leaf subclass with the given name.
+    
+    def leaf(name)
+      controller = klass('Controller', 'Autumn::Leaf') do |leaf|
+        leaf.newline!
+        leaf << '# Typing "!about" displays some basic information about this leaf.'
+        leaf.newline!
+        about_command = leaf.method('about_command', 'stem', 'sender', 'reply_to', 'msg') do |about|
+          about << '# This method renders the file "about.txt.erb"'
+        end
+      end
+      controller.doc = "Controller for the #{name.camelcase} leaf."
+      return controller
+    end
+  end
+end

data/lib/autumn/console_boot.rb

@@ -0,0 +1,9 @@
+# Used by the script/console script to load the Autumn environment when IRb
+# is executed.
+
+require 'autumn/genesis'
+
+# We set APP_ROOT in the script/console file to set it for the scope of that
+# file. We have to set it again in here for the scope of the IRb session.
+@genesis = Autumn::Genesis.new
+@genesis.boot! false

data/lib/autumn/ctcp.rb

@@ -0,0 +1,250 @@
+# Defines the Autum::CTCP class, which implements CTCP support.
+
+require 'time'
+
+module Autumn
+
+  # A listener for a Stem that listens for and handles CTCP requests. You can
+  # add CTCP support for your IRC client by instantiating this object and
+  # passing it to the Stem#add_listener method.
+  #
+  # CTCP stands for Client-to-Client Protocol and is a way that IRC clients and
+  # servers can request and transmit more information about each other. Modern
+  # IRC clients all have CTCP support, and many servers expect or assume that
+  # their clients support CTCP. CTCP is also used as a basis for further
+  # extensions to IRC, such as DCC and XDCC.
+  #
+  # This class implements the spec defined at http://www.invlogic.com/irc/ctcp.html
+  #
+  # Because some IRC servers will disconnect clients that send a large number of
+  # messages in a short period of time, this listener will only send one CTCP
+  # reply per second, with up to a maximum of 10 replies waiting in the queue
+  # (after which new requests are ignored). These values can be adjusted in the
+  # initialization options.
+  #
+  # This class acts as a listener plugin: Any of the methods specified below can
+  # be implemented by any other listener, and will be invoked by this listener
+  # when appropriate.
+  #
+  # To respond to incoming CTCP requests, you should implement methods of the
+  # form <tt>ctcp_*_request</tt>, where "*" is replaced with the lowercase name
+  # of the CTCP command. (For example, to handle VERSION requests, implement
+  # +ctcp_version_request+). This method will be invoked whenever a request is
+  # received by the IRC client. It will be given the following parameters:
+  #
+  # 1. the CTCP instance that parsed the request,
+  # 2. the Stem instance that received the request,
+  # 3. the person who sent the request (a hash in the form of that used by Stem;
+  #    see Stem#add_listener for more information), and
+  # 4. an array of arguments passed along with the request.
+  #
+  # In addition, you can implement +ctcp_request_received+, which will then be
+  # invoked for any and all incoming CTCP requests. It is passed the following
+  # arguments:
+  #
+  # 1. the name of the request, as a lowercase symbol,
+  # 2. the CTCP instance that parsed the request,
+  # 3. the Stem instance that received the request,
+  # 4. the person who sent the request (a sender hash -- see the Leaf docs), and
+  # 5. an array of arguments passed along with the request.
+  #
+  # This class will by default respond to some incoming CTCP requests and
+  # generate appropriate replies; however, it does not implement any specific
+  # behavior for parsing incoming replies. If you wish to parse replies, you
+  # should implement methods in your listener of the form
+  # <tt>ctcp_*_response</tt>, with the "*" character replaced as above. This
+  # method will be invoked whenever a reply is received by this listener. You
+  # can also implement <tt>ctcp_response_received</tt> just as above. The
+  # parameters for these methods are the same as those listed above.
+  #
+  # Responses are assumed to be any CTCP messages that are sent as a NOTICE (as
+  # opposed to a PRIVMSG). Because they are NOTICEs, your program should not
+  # send a message in response.
+  #
+  # In addition to responding to incoming CTCP requests and replies, your
+  # listener can use its stem to send CTCP requests and replies. See the added
+  # method for more detail.
+
+  class CTCP
+    # Format of an embedded CTCP request.
+    CTCP_REQUEST = /\x01(.+?)\x01/
+    # CTCP commands whose arguments are encoded according to the CTCP spec (as
+    # opposed to other commands, whose arguments are plaintext).
+    ENCODED_COMMANDS = [ 'VERSION', 'PING' ]
+    
+    # Creates a new CTCP parser. Options are:
+    #
+    # +reply_queue_size+:: The maximum number of pending replies to store in the
+    #                      queue, after which new CTCP requests are ignored.
+    # +reply_rate+:: The minimum time, in seconds, between consecutive CTCP
+    #                replies.
+    
+    def initialize(options={})
+      @options = options
+      @options[:reply_queue_size] ||= 10
+      @options[:reply_rate] ||= 0.25
+      @reply_thread = Hash.new
+      @reply_queue = Hash.new do |hsh, key|
+        hsh[key] = ForgetfulQueue.new(@options[:reply_queue_size])
+        @reply_thread[key] = Thread.new(key) do |stem|
+          loop do #TODO wake thread when stem is quitting so this thread can terminate?
+            reply = @reply_queue[stem].pop
+            stem.notice reply[:recipient], reply[:message]
+            sleep @options[:reply_rate]
+          end
+        end
+        hsh[key]
+      end
+    end
+    
+    # Parses CTCP requests in a PRIVMSG event.
+    
+    def irc_privmsg_event(stem, sender, arguments) # :nodoc:
+      arguments[:message].scan(CTCP_REQUEST).flatten.each do |ctcp|
+        ctcp_args = ctcp.split(' ')
+        request = ctcp_args.shift
+        ctcp_args = ctcp_args.map { |arg| unquote arg } if ENCODED_COMMANDS.include? request
+        meth = "ctcp_#{request.downcase}_request".to_sym
+        stem.broadcast meth, self, stem, sender, ctcp_args
+        stem.broadcast :ctcp_request_received, request.downcase.to_sym, self, stem, sender, ctcp_args
+      end
+    end
+    
+    # Parses CTCP responses in a NOTICE event.
+    
+    def irc_notice_event(stem, sender, arguments) # :nodoc:
+      arguments[:message].scan(CTCP_REQUEST).flatten.each do |ctcp|
+        ctcp_args = ctcp.split(' ')
+        request = ctcp_args.shift
+        ctcp_args = ctcp_args.map { |arg| unquote arg } if ENCODED_COMMANDS.include? request
+        meth = "ctcp_#{request.downcase}_response".to_sym
+        stem.broadcast meth, self, stem, sender, ctcp_args
+        stem.broadcast :ctcp_response_received, request.downcase.to_sym, self, stem, sender, ctcp_args
+      end
+    end
+    
+    # Replies to a CTCP VERSION request by sending:
+    #
+    # * the name of the IRC client ("Autumn, a Ruby IRC framework"),
+    # * the operating system name and version, and
+    # * the home page URL for Autumn.
+    #
+    # To determine the OS name and version, this method runs the <tt>uname
+    # -sr</tt> command; if your operating system does not support this command,
+    # you should override this method.
+    #
+    # Although the CTCP spec states that the VERSION response should be three
+    # encoded strings (as shown above), many modern clients expect one plaintext
+    # string. If you'd prefer compatibility with those clients, you should
+    # override this method to return a single plaintext string and remove the
+    # VERSION command from +ENCODED_COMMANDS+.
+    
+    def ctcp_version_request(handler, stem, sender, arguments)
+      return unless handler == self
+      send_ctcp_reply stem, sender[:nick], 'VERSION', "Autumn #{AUTUMN_VERSION}, a Ruby IRC framework", `uname -sr`, "http://github.com/RISCfuture/autumn"
+    end
+    
+    # Replies to a CTCP PING request by sending back the same arguments as a
+    # PONG reply.
+    
+    def ctcp_ping_request(handler, stem, sender, arguments)
+      return unless handler == self
+      send_ctcp_reply stem, sender[:nick], 'PING', *arguments
+    end
+    
+    # Replies to a CTCP TIME request by sending back the local time in RFC-822
+    # format.
+    
+    def ctcp_time_request(handler, stem, sender, arguments)
+      return unless handler == self
+      send_ctcp_reply stem, sender[:nick], 'TIME', Time.now.rfc822
+    end
+    
+    # Adds a CTCP reply to the queue. You must pass the Stem instance that will
+    # be sending this reply, the recipient (channel or nick), and the name of
+    # the CTCP command (as an uppercase string). Any additional arguments are
+    # taken to be arguments of the CTCP reply, and are thus encoded and joined
+    # by space characters, as specified in the CTCP white paper. The arguments
+    # should all be strings.
+    #
+    # +recipient+ can be a nick, a channel name, or a sender hash, as necessary.
+    # Encoding of arguments is only done for commands in +ENCODED_COMMANDS+.
+    
+    def send_ctcp_reply(stem, recipient, command, *arguments)
+      recipient = recipient[:nick] if recipient.kind_of? Hash
+      @reply_queue[stem] << { :recipient => recipient, :message => make_ctcp_message(command, *arguments) }
+    end
+    
+    # When this listener is added to a stem, the stem gains the ability to send
+    # CTCP messages directly. Methods of the form <tt>ctcp_*</tt>, where "*" is
+    # the lowercase name of a CTCP action, will be forwarded to this listener,
+    # which will send the CTCP message. The first parameter of the method is the
+    # nick of one or more recipients; all other parameters are parameters for
+    # the CTCP command. See the CTCP spec for more information on the different
+    # commands and parameters available.
+    #
+    # For example, to send an action (such as "/me is cold") to a channel:
+    #
+    #  stem.ctcp_action "#channel", "is cold"
+    #
+    # In addition, the stem gains the ability to send CTCP replies. Replies are
+    # messages that are added to this class's reply queue, adding flood abuse
+    # prevention. To send a reply, call a Stem method of the form
+    # <tt>ctcp_reply_*</tt>, where "*" is the command name you are replying to,
+    # in lowercase. Pass first the nick or sender hash of the recipient, then
+    # any parameters as specified by the CTCP spec. For example, to respond to a
+    # CTCP VERSION request:
+    #
+    #  stem.ctcp_reply_version sender, 'Bot Name', 'Computer Name', 'Other Info'
+    #
+    # (Note that responding to VERSION requests is already handled by this class
+    # so you'll need to either override or delete the ctcp_version_request
+    # method to do this.)
+    
+    def added(stem)
+      stem.instance_variable_set :@ctcp, self
+      class << stem
+        def method_missing(meth, *args)
+          if meth.to_s =~ /^ctcp_reply_([a-z]+)$/ then
+            @ctcp.send_ctcp_reply self, args.shift, $1.to_s.upcase, *args
+          elsif meth.to_s =~ /^ctcp_([a-z]+)$/ then
+            privmsg args.shift, @ctcp.make_ctcp_message($1.to_s.upcase, *args)
+          else
+            super
+          end
+        end
+      end
+    end
+    
+    # Creates a CTCP-formatted message with the given command (uppercase string)
+    # and arguments (strings). The string returned is suitable for transmission
+    # over IRC using the PRIVMSG command.
+    
+    def make_ctcp_message(command, *arguments)
+      arguments = arguments.map { |arg| quote arg } if ENCODED_COMMANDS.include? command
+      "\01#{arguments.unshift(command).join(' ')}\01"
+    end
+    
+    private
+    
+    def quote(str)
+      chars = str.split('')
+      chars.map! do |char|
+        case char
+          when "\0" then '\0'
+          when "\1" then '\1'
+          when "\n" then '\n'
+          when "\r" then '\r'
+          when " " then '\@'
+          when "\\" then '\\\\'
+          else char
+        end
+      end
+      return chars.join
+    end
+    
+    def unquote(str)
+      str.gsub('\\\\', '\\').gsub('\@', " ").gsub('\r', "\r").gsub('\n', "\n").gsub('\1', "\1").gsub('\0', "\0")
+    end
+  end
+end

data/lib/autumn/daemon.rb

@@ -0,0 +1,207 @@
+# Defines the Autumn::Daemon class, which stores information on the different
+# implementations of IRC by different server daemons.
+
+module Autumn
+  
+  # Describes an IRC server daemon program. Different IRC servers run off of
+  # different IRC daemons, each of which has a slightly different implementation
+  # of the IRC protocol. To encapsulate this, the Daemon class stores the names
+  # of some of the more common IRC server types, as well as the unique
+  # information about those daemons, such as supported usermodes, response
+  # codes, and supported channel types.
+  #
+  # An instance of Daemon is an IRC server type. The Daemon class keeps a
+  # catalog of all instances, assigning each a descriptive name (for example,
+  # "Unreal" for the UnrealIRCd program, a popular IRC server daemon).
+  #
+  # A Daemon instance can be queried for information about the IRC server type,
+  # as necessary to parse messages from that IRC server.
+  #
+  # A "default" daemon will also be created representing a common denominator of
+  # IRC features, which is used in situations where a server's exact type is
+  # unknown. This daemon will consist of all non-conflicting entries among the
+  # defined daemons.
+  #
+  # In addition to the methods and attributes below, you can also call predicate
+  # methods such as <tt>usermode?</tt> and <tt>channel_prefix?</tt> to test if a
+  # character is in a set of known modes/privileges/prefixes, or if a number is
+  # in the set of known events.
+  
+  class Daemon
+        
+    # Creates a new Daemon instance associated with a given name. You must also
+    # pass in the hashes for it to store.
+    
+    def initialize(name, info)
+      if name.nil? and info.nil? then # it's the default hash
+        raise "Already created a default Daemon" if self.class.class_variable_defined? :@@default
+        @usermode = Hash.parroting
+        @privilege = Hash.parroting
+        @user_prefix = Hash.parroting
+        @channel_prefix = Hash.parroting
+        @channel_mode = Hash.parroting
+        @server_mode = Hash.parroting
+        @event = Hash.parroting
+        @default = true
+      else
+        @usermode = Hash.parroting(info['usermode'])
+        @privilege = Hash.parroting(info['privilege'])
+        @user_prefix = Hash.parroting(info['user_prefix'])
+        @channel_prefix = Hash.parroting(info['channel_prefix'])
+        @channel_mode = Hash.parroting(info['channel_mode'])
+        @server_mode = Hash.parroting(info['server_mode'])
+        @event = Hash.parroting(info['event'])
+        @@instances[name] = self
+
+        # Build up our default so it contains all keys with no conflicting
+        # values across different server specs. Delete keys from the default
+        # hash for which we found duplicates.
+        info.each do |hname, hsh|
+          next unless @@default.respond_to? hname.to_sym
+          default_hash = @@default.send(hname.to_sym)
+          
+          uniques = hsh.reject { |k, v| default_hash.include? k }
+          default_hash.update uniques
+          default_hash.reject! { |k, v| hsh.include?(k) and hsh[k] != v }
+        end
+      end
+    end
+    
+    # Returns a Daemon instance by associated name.
+    
+    def self.[](name)
+      @@instances[name]
+    end
+    
+    # Returns the fallback server type.
+    
+    def self.default
+      @@default
+    end
+    
+    # Yields the name of each Daemon registered with the class.
+    
+    def self.each_name
+      @@instances.keys.sort.each { |name| yield name }
+    end
+    
+    # Hash of usermode characters (e.g., <tt>i</tt>) to their symbol
+    # representations (e.g., <tt>:invisible</tt>).
+    
+    def usermode
+      @default ? @usermode : @@default.usermode.merge(@usermode)
+    end
+    
+    # Hash of user privilege characters (e.g., <tt>v</tt>) to their symbol
+    # representations (e.g., <tt>:voiced</tt>).
+    
+    def privilege
+      @default ? @privilege : @@default.privilege.merge(@privilege)
+    end
+    
+    # Hash of user privilege prefixes (e.g., <tt>@</tt>) to their symbol
+    # representations (e.g., <tt>:operator</tt>).
+    
+    def user_prefix
+      @default ? @user_prefix : @@default.user_prefix.merge(@user_prefix)
+    end
+    
+    # Hash of channel prefixes (e.g., <tt>&</tt>) to their symbol
+    # representations (e.g., <tt>:local</tt>).
+    
+    def channel_prefix
+      @default ? @channel_prefix : @@default.channel_prefix.merge(@channel_prefix)
+    end
+    
+    # Hash of channel mode characters (e.g., <tt>m</tt>) to their symbol
+    # representations (e.g., <tt>:moderated</tt>).
+    
+    def channel_mode
+      @default ? @channel_mode : @@default.channel_mode.merge(@channel_mode)
+    end
+    
+    # Hash of server mode characters (e.g., <tt>H</tt>) to their symbol
+    # representations (e.g., <tt>:hidden</tt>).
+    
+    def server_mode
+      @default ? @server_mode : @@default.server_mode.merge(@server_mode)
+    end
+    
+    # Hash of numerical event codes (e.g., 372) to their symbol representations
+    # (e.g., <tt>:motd</tt>).
+    
+    def event
+      @default ? @event : @@default.event.merge(@event)
+    end
+    
+    # Returns true if the mode string (e.g., "+v") appears to be changing a user
+    # privilege as opposed to a channel mode.
+    
+    def privilege_mode?(mode)
+      raise ArgumentError, "Invalid mode string '#{mode}'" unless mode =~ /^[\+\-]\S+$/
+      mode.except_first.chars.all? { |c| privilege? c }
+    end
+
+    # Returns true if the first character(s) of a nick are valid privilege
+    # prefixes.
+
+    def nick_prefixed?(nick)
+      user_prefix? nick[0,1]
+    end
+
+    # Given a nick, returns that nick stripped of any privilege characters on
+    # the left side.
+
+    def just_nick(name)
+      nick = name.dup
+      while nick_prefixed?(nick)
+        nick.slice! 0, 1
+      end
+      return nick
+    end
+
+    # Given a nick, returns the privileges granted to this nick, as indicated by
+    # the prefix characters. Returns :unvoiced if no prefix characters are
+    # present. Returns an array of privileges if multiple prefix characters are
+    # present.
+
+    def nick_privilege(name)
+      privs = Set.new
+      nick = name.dup
+      while user_prefix? nick[0,1]
+        privs << user_prefix[nick[0,1]]
+        nick.slice! 0, 1
+      end
+      case privs.size
+        when 0 then :unvoiced
+        when 1 then privs.only
+        else privs
+      end
+    end
+    
+    def method_missing(meth, *args) # :nodoc:
+      if meth.to_s =~ /^([a-z_]+)\?$/ then
+        base = $1
+        if (instance_variables.include?("@#{base}") or instance_variables.include?("@#{base}".to_sym)) and args.size == 1 then
+          if base.end_with?('_prefix') and args.only.kind_of?(Numeric) then
+            arg = args.only.chr
+          else
+            arg = args.only
+          end
+          eval "#{base}.include? #{arg.inspect}"
+        end
+      else
+        super
+      end
+    end
+    
+    def inspect # :nodoc:
+      "#<#{self.class.to_s} #{@@instances.index self}>"
+    end
+    
+    private
+    
+    @@instances = Hash.new
+    @@default = self.new(nil, nil)
+  end
+end