cinch 0.2.9 → 0.3.0

data/README.rdoc

@@ -1,8 +1,7 @@
-= Cinch: The IRC Microframework
+= Cinch: The IRC Bot Building Framework
 
 == Description
-
-Cinch is an IRC Microframework for quickly creating IRC bots
+Cinch is an IRC Bot Building Framework for quickly creating IRC bots
 in Ruby with minimal effort.
 It provides a minimal interface based on plugins and rules. It's as simple as creating a
 plugin, defining a rule, and watching your profits flourish.
@@ -14,7 +13,6 @@ If you'd like to test your own Cinch experiments you can do so in the cinch IRC
 on {irc.freenode.org}[irc://irc.freenode.org/cinch]. Support is also welcome here.
 
 == Installation
-The latest version of Cinch is 0.2
 
 === RubyGems
 You can install the latest version of Cinch using RubyGems
@@ -25,7 +23,6 @@ Alternatively you can check out the latest code directly from Github
  git clone http://github.com/injekt/cinch.git
 
 == Example
-
 Your typical <em>Hello, World</em> application would go something like this:
 
  require 'cinch'
@@ -62,17 +59,18 @@ other Ruby script.
 
  ruby hello.rb
 
-Cinch also parses the command line for options, to save you having to configure options within your script.
+Cinch also parses the command line for options, to save you having to configure 
+options within your script.
 
  ruby hello.rb -s irc.freenode.org -n Coolbot
- ruby hello.rb --channels foo,bar
+ ruby hello.rb -C foo,bar
 
-Doing a <b>ruby hello.rb -h</b> provides all possible command line options. When using the <em>--channels</em>
-option, the channel prefix is option, and if none is given the channel will be prefixed with a hash (#) 
+Doing a <b>ruby hello.rb -h</b> provides all possible command line options. When using the <em>-C</em>
+or <em>--channels</em> option, the channel prefix is option, and if none is given the channel
+will be prefixed with a hash (#) 
 character 
 
 == Plugins
-
 Plugins are invoked using the command prefix character (which by default is set to <b>!</b>). You can
 also tell Cinch to ignore any command prefix and instead use the bots username. This would provide
 a result similar to this:
@@ -172,8 +170,7 @@ before sending me a pull request. Alternatively paste the example and inform me
 channel or by email
 
 == Authors
-Just me at the moment, sad poor lonely me...
-* {Lee Jarvis}[http://blog.injekt.net]
+* {Lee Jarvis}[http://injekt.net]
 
 == Notes
 * RDoc API documentation is available {here}[http://rdoc.injekt.net/cinch]
@@ -189,5 +186,4 @@ request once one patch has been submitted. Any contribution is welcome and appre
 == TODO
 * More specs
 * More documentation
-* More examples
 

data/Rakefile

@@ -1,14 +1,19 @@
 require "rake"
 require "rake/clean"
 require "rake/gempackagetask"
-require "rake/rdoctask"
 require "spec/rake/spectask"
 
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
+  require 'rake/rdoctask'
+end
+
 require 'lib/cinch'
 
 NAME = 'cinch'
 VERSION = Cinch::VERSION
-TITLE = "Cinch: The IRC Microframework"
+TITLE = "Cinch: The IRC Bot Building Framework"
 CLEAN.include ["*.gem", "rdoc"]
 RDOC_OPTS = [
   "-U", "--title", TITLE,

data/lib/cinch.rb

@@ -9,7 +9,7 @@ require 'cinch/rules'
 require 'cinch/base'
 
 module Cinch
-  VERSION = '0.2.9'
+  VERSION = '0.3.0'
 
   # Setup bot options and return a new Cinch::Base instance
   def self.setup(ops={}, &blk)

data/lib/cinch/base.rb

@@ -1,8 +1,5 @@
 module Cinch
 
-  # == Author
-  # * Lee Jarvis - ljjarvis@gmail.com
-  #
   # == Description
   # The base for an IRC connection
   # TODO: More documentation
@@ -17,6 +14,9 @@ module Cinch
   #  bot.plugin "say :text" do |m|
   #    m.reply m.args[:text]
   #  end
+  #
+  # == Author
+  # * Lee Jarvis - ljjarvis@gmail.com
   class Base
 
     # A Hash holding rules and attributes
@@ -28,6 +28,12 @@ module Cinch
     # An OpenStruct holding all configuration options
     attr_reader :options
 
+    # Hash of custom rule patterns
+    attr_reader :custom_patterns
+
+    # Our IRC::Socket instance
+    attr_reader :irc
+
     # Default options hash
     DEFAULTS = {
       :port => 6667,
@@ -64,7 +70,14 @@ module Cinch
 
       @rules = Rules.new
       @listeners = {}
-      @custom_patterns = {}
+
+      @custom_patterns = {
+        'digit' => "(\\d+?)",
+        'word' => "([a-zA-Z_]+?)",
+        'string' => "(\\w+?)",
+        'upper' => "([A-Z]+?)",
+        'lower' => "([a-z]+?)",
+      }
 
       @irc = IRC::Socket.new(options[:server], options[:port])
       @parser = IRC::Parser.new
@@ -78,7 +91,7 @@ module Cinch
       end
 
       if @options.respond_to?(:channels)
-        on(376) { @options.channels.each {|c| @irc.join(c) } }
+        on("004") { @options.channels.each {|c| @irc.join(c) } }
       end
     end
 
@@ -123,6 +136,7 @@ module Cinch
         @rules.add_rule(rule, keys, options, blk)
       end
     end
+    alias :rule :plugin
 
     # Add new listeners
     #
@@ -130,6 +144,11 @@ module Cinch
     #  on(376) do |m|
     #    m.join "#mychan"
     #  end
+    #
+    # Note that when adding listeners for numberic IRC replies which
+    # begin with a 0 (digit), make sure you define the command as a
+    # String and not Integer. This is because 001.to_s == "1" so the
+    # command will not work as expected.
     def on(*commands, &blk)
       commands.map {|x| x.to_s.downcase.to_sym }.each do |cmd|
         if @listeners.key?(cmd)
@@ -153,28 +172,28 @@ module Cinch
     # * upper - matches [A-Z]+
     #
     # == Examples
-    # For capturing individual words
+    # === Capturing individual words
     #  bot.plugin("say :text-word")
     # * Does match !say foo
     # * Does not match !say foo bar baz
     #
-    # For capturing digits
+    # === Capturing digits
     #  bot.plugin("say :text-digit")
     # * Does match !say 3
     # * Does not match !say 3 4
     # * Does not match !say foo
     #
-    # For both
+    # === Both digit and word
     #  bot.plugin("say :n-digit :text-word")
     # * Does match !say 3 foo
     # * Does not match !say 3 foo bar
     #
-    # For capturing until the end of the line
+    # === Capturing until the end of the line
     #  bot.plugin("say :text")
     # * Does match !say foo
     # * Does match !say foo bar
     #
-    # Or mix them all
+    # === Or mix them all
     #  bot.plugin("say :n-digit :who-word :text")
     #
     # Using "!say 3 injekt some text here" would provide
@@ -193,22 +212,14 @@ module Cinch
           Regexp.escape(match)
         else
           k = $2
-          if k =~ /\-(\w+)$/
+          if k =~ /\-\w+$/
             key, type = k.split('-')
             keys << key[1..-1]
-
-            case type
-            when 'digit'; "(\\d+?)"
-            when 'word'; "([a-zA-Z_]+?)"
-            when 'string'; "(\\w+?)"
-            when 'upper'; "([A-Z]+?)"
-            when 'lower'; "([a-z]+?)"
+            
+            if @custom_patterns.include?(type)
+              @custom_patterns[type]
             else
-              if @custom_patterns.include?(type)
-                @custom_patterns[type]
-              else
-                "([^\x00\r\n]+?)"
-              end
+              "([^\x00\r\n]+?)"
             end
           else
             keys << k[1..-1]
@@ -222,20 +233,19 @@ module Cinch
     # Add a custom 'type', for rule validation
     #
     # == Example
-    # bot = Cinch.setup do
-    #   server 'irc.freenode.org'
-    #   port 6667
-    # end
+    #  bot = Cinch.setup do
+    #    server 'irc.freenode.org'
+    #    port 6667
+    #  end
     #
-    # bot.add_custom_pattern(:number, "[0-9]")
+    #  bot.add_custom_pattern(:number, "[0-9]")
     #
-    # bot.plugin("getnum :foo-number") do |m|
-    #   m.reply "Your number was: #{m.args[:foo]}"
-    # end
+    #  bot.plugin("getnum :foo-number") do |m|
+    #    m.reply "Your number was: #{m.args[:foo]}"
+    #  end
     def add_custom_pattern(name, pattern)
       @custom_patterns[name.to_s] = "(#{pattern.to_s})"
     end
-    alias :add_custom_type :add_custom_pattern # backwards
     alias :add_pattern :add_custom_pattern
 
     # Run run run

data/lib/cinch/irc.rb

@@ -8,9 +8,7 @@ require 'irc/message'
 require 'irc/socket'
 
 module Cinch
-  # == Author
-  # * Lee Jarvis - ljjarvis@gmail.com
-  #
+
   # == Description
   # Cinch::IRC provides tools to interact with an IRC server, this
   # includes reading/writing/parsing and building a message response.
@@ -38,6 +36,8 @@ module Cinch
   #    end
   #  end
   #
+  # == Author
+  # * Lee Jarvis - ljjarvis@gmail.com
   module IRC
 
   end

data/lib/cinch/irc/message.rb

@@ -1,18 +1,17 @@
 module Cinch
   module IRC
     
-    # == Author
-    # * Lee Jarvis - ljjarvis@gmail.com
-    #
     # == Description
-    # IRC::Message is a nicely encapsulated IRC message object. Used directly by 
-    # IRC::Parser#parse_servermessage and sent to every plugin defined. It does
-    # not do any parsing of itself, that's all down to the parser
-    #
-    # == See
-    # * Cinch::IRC::Parser#parse_servermessage
+    # IRC::Message provies a nicely encapsulated IRC message object. Used directly by 
+    # IRC::Parser#parse and sent to any plugin or listener defined. 
     #
     # TODO: Add more documentation
+    # 
+    # == See Also
+    # * Cinch::IRC::Parser#parse
+    #
+    # == Author
+    # * Lee Jarvis - ljjarvis@gmail.com
     class Message
 
       # Message prefix
@@ -74,16 +73,21 @@ module Cinch
         @data.delete(var)
       end
 
+      # Alter an attribute
+      def alter(var, val)
+        if @data.key?(var)
+          @data[var] = val
+        end
+      end
+
       # Check if our message was sent privately
       def private?
         !@data[:channel]
       end
 
-      # Add the nick/user/host attributes
-      def apply_user(nick, user, host)
-        @data[:nick] = nick
-        @data[:user] = user
-        @data[:host] = host
+      # Check if our message was sent publicly (in a channel)
+      def public?
+        !private?
       end
 
       # Reply to a channel or user, probably the most commonly used helper

data/lib/cinch/irc/parser.rb

@@ -1,9 +1,6 @@
 module Cinch
   module IRC
 
-    # == Author
-    # * Lee Jarvis - ljjarvis@gmail.com
-    #
     # == Description
     # Parse incoming IRC lines and extract data, returning a nicely
     # encapsulated Cinch::IRC::Message
@@ -19,6 +16,9 @@ module Cinch
     #  message.nick #=> foo
     #  message.channel #=> #mychan
     #  message.text #=> ding dong!
+    #
+    # == Author
+    # * Lee Jarvis - ljjarvis@gmail.com
     class Parser
 
       # A hash holding all of our patterns
@@ -79,7 +79,7 @@ module Cinch
 
       # Parse the incoming raw IRC string and return
       # a nicely formatted IRC::Message
-      def parse_servermessage(raw)
+      def parse(raw)
         raise ArgumentError, raw unless raw && matches = raw.match(pattern(:message))
 
         prefix, command, parameters = matches.captures
@@ -90,17 +90,19 @@ module Cinch
         m = IRC::Message.new(raw, prefix, command, params)
 
         if prefix && userhost = parse_userhost(prefix)
-          m.apply_user(*userhost)
+          nick, user, host = userhost
+          m.add(:nick, nick)
+          m.add(:user, user)
+          m.add(:host, host)
 
           unless m.params.empty?
-            m[:recipient] = m.params.first
-            m[:channel] = m[:recipient] if valid_channel?(m[:recipient])
+            m.add(:recipient, m.params.first)
+            m.add(:channel, m.recipient) if valid_channel?(m.recipient)
           end
         end
 
         m # Return our IRC::Message
       end
-      alias :parse :parse_servermessage
 
       # Parse the prefix returned from the server
       # and return an Array of [nick, user, host] or 

data/lib/cinch/irc/socket.rb

@@ -1,10 +1,8 @@
 module Cinch
   module IRC
-    # == Author
-    # * Lee Jarvis - ljjarvis@gmail.com
-    #
+
     # == Description
-    # This class has been directly take from the irc-socket library. Original documentation
+    # This class has been directly taken from the irc-socket library. Original documentation
     # for this class can be found {here}[http://rdoc.injekt.net/irc-socket].
     #
     # IRCSocket is an IRC wrapper around a TCPSocket. It implements all of the major 
@@ -37,6 +35,9 @@ module Cinch
     #
     #    puts irc.read
     #  end
+    #
+    # == Author
+    # * Lee Jarvis - ljjarvis@gmail.com 
     class Socket
 
       # The server our socket is connected to
@@ -166,7 +167,7 @@ module Cinch
 
       # Send JOIN command - Join a channel with given password
       def join(channel, password=nil)
-        write("JOIN #{channel}")
+        write_optional("JOIN #{channel}", password)
       end
 
       # Send PART command

data/lib/cinch/rules.rb

@@ -1,8 +1,5 @@
 module Cinch
 
-  # == Author
-  # * Lee Jarvis - ljjarvis@gmail.com
-  #
   # == Description
   # Every rule defined through the Cinch::Base#plugin method becomes an instance 
   # of this class. Each rule consists of keys used for named parameters, a hash
@@ -10,25 +7,28 @@ module Cinch
   #
   # When a rule matches an IRC message, all options with be checked, then all
   # callbacks will be invoked.
+  #
+  # == Author
+  # * Lee Jarvis - ljjarvis@gmail.com
   class Rule < Struct.new(:rule, :keys, :options, :callbacks)
     def initialize(rule, keys, options, callback)
       callbacks = [callback]
       super(rule, keys, options, callbacks)
     end
 
-    # Execute all callbacks, passing an Cinch::IRC::Message to them
+    # Execute all callbacks, passing a Cinch::IRC::Message to them
     def execute(message)
       options.keys.each do |key|
         case key
         when :nick, :nicks
-          return unless validate(options[:nick], message.nick)
+          return unless validate(options[:nick] || options[:nicks], message.nick)
         when :host, :hosts
-          return unless validate(options[:host], message.host)
+          return unless validate(options[:host] || options[:hosts], message.host)
         when :user, :users
-          return unless validate(options[:user], message.user)
+          return unless validate(options[:user] || options[:users], message.user)
         when :channel, :channels
           if message.channel
-            return unless validate(options[:channel], message.channel)
+            return unless validate(options[:channel] || options[:channels], message.channel)
           end
         end
       end
@@ -43,7 +43,7 @@ module Cinch
       if option.is_a?(Array)
         return unless option.any?{|o| o == attr }
       else
-        return unless options.to_s == attr
+        return unless option.to_s == attr
       end
       true
     end
@@ -54,9 +54,6 @@ module Cinch
     end
   end
 
-  # == Author
-  # * Lee Jarvis - ljjarvis@gmail.com
-  #
   # == Description
   # This class provides an interface to manage rules. A rule should only ever be
   # added using the Rules#add_rule method and retrieved using the Rules#get_rule 
@@ -87,6 +84,9 @@ module Cinch
   #  rules.get_rule('foo')
   #  rules.options = {:foo => 'bar'}
   #  rules.options[:bar] = 'baz'
+  #
+  # == Author
+  # * Lee Jarvis - ljjarvis@gmail.com
   class Rules
     def initialize
       @rules = {}

data/spec/base_spec.rb

@@ -20,9 +20,19 @@ describe "Cinch::Base" do
       @base.listeners.should include :"433"
     end
 
-    it "should add a 376 listener, only if channels are set" do
-      @base.listeners.should_not include :'376'
-      @full.listeners.should include :'376'
+    it "should add a 004 listener, only if channels are set" do
+      @base.listeners.should_not include :'004'
+      @full.listeners.should include :'004'
+    end
+
+    it "should add a 433 nick taken listener" do
+      @base.listeners.should include :'433'
+    end
+
+    it "should add default custom_patterns" do
+      [:digit, :word, :string, :upper, :lower].each do |l|
+        @base.custom_patterns.should include l.to_s
+      end
     end
   end
 

data/spec/irc/parser_spec.rb

@@ -56,7 +56,7 @@ describe "IRC::Parser" do
     end
   end
 
-  describe "#parse_servermessage" do
+  describe "#parse" do
     it "should return an IRC::Message" do
       @parser.parse("foo :bar").should be_kind_of(Cinch::IRC::Message)
     end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 9
-  version: 0.2.9
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Lee 'injekt' Jarvis
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-07 00:00:00 +01:00
+date: 2010-05-18 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -31,7 +31,7 @@ dependencies:
         version: 1.3.0
   type: :development
   version_requirements: *id001
-description: An IRC Microframework
+description: An IRC Bot Building Framework
 email: ljjarvis@gmail.com
 executables: []
 
@@ -77,7 +77,7 @@ post_install_message:
 rdoc_options: 
 - --quiet
 - --title
-- "Cinch: The IRC Microframework"
+- "Cinch: The IRC Bot Building Framework"
 - --main
 - README.rdoc
 require_paths: 
@@ -104,6 +104,6 @@ rubyforge_project:
 rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
-summary: An IRC Microframework
+summary: An IRC Bot Building Framework
 test_files: []