cinch 0.1 → 0.2

data/README.rdoc

@@ -10,7 +10,11 @@ plugin, defining a rule, and watching your profits flourish.
 Cinch will do all of the hard work for you, so you can spend time creating cool plugins
 and extensions to wow your internet peers.
 
+Cinch is not a fully fledged IRC framework, its base is extremely small. If you're looking
+for a more controlled library check out {silverplatter-irc}[http://github.com/apeiros/silverplatter-irc].
+
 == Installation
+The latest version of Cinch is 0.2
 
 === RubyGems
 You can install the latest version of Cinch using RubyGems
@@ -95,9 +99,28 @@ the rules given, for example if we want to reply only if the nick sending the me
 could pass the 'nick' option to the hash.
 
  bot.plugin("join :channel", :nick => 'injekt') do |m|
-   m.join #{m.args[:channel]}
+   bot.join #{m.args[:channel]}
+ end
+
+== Named Parameter Types
+Since version 0.2, Cinch supports named parameter types. Although at the moment you're constrained
+to the <i>digit</i>, <i>string</i> and <i>word</i> types. It means stuff like the this works:
+
+ bot.plugin("say :n-digit :text") do |m|
+   m.args[:n].to_i.times {
+     m.reply m.args[:text]
+   end
  end
 
+This would provide the following output on IRC
+
+ injekt> !say foo bar
+ injekt> !say 2 foo bar
+ Cinch> foo bar
+ Cinch> foo bar
+
+* See Cinch::Base#compile for more information
+
 == Authors
 Just me at the moment, sad poor lonely me...
 * {Lee Jarvis}[http://blog.injekt.net]

data/examples/hello.rb

@@ -0,0 +1,13 @@
+require 'cinch'
+
+bot = Cinch.setup do 
+  server "irc.freenode.org"
+  channels %w( #cinch )
+end
+
+bot.plugin "hello" do |m|
+  m.reply "Hello, #{m.nick}!"
+end
+
+bot.run
+

data/examples/join_part.rb

@@ -0,0 +1,26 @@
+require 'cinch'
+
+bot = Cinch.setup do 
+  server "irc.freenode.org"
+  nick "CinchBot"
+  channels %w( #cinch )
+end
+
+# Who should be able to access these plugins
+admin = 'injekt'
+
+bot.plugin "join :channel", :nick => admin do |m|
+  bot.join m.args[:channel]
+end
+
+bot.plugin "part :channel", :nick => admin do |m|
+  bot.part m.args[:channel]
+end
+
+# Part current channel if none is given
+bot.plugin "part", :nick => admin do |m|
+  bot.part m.channel
+end
+
+bot.run
+

data/examples/msg.rb

@@ -0,0 +1,14 @@
+require 'cinch'
+
+bot = Cinch.setup do 
+  server "irc.freenode.org"
+  nick "CinchBot"
+  channels %w/ #cinch /
+end
+
+bot.plugin("msg :who :text") do |m|
+  bot.privmsg m.args[:who], m.args[:text]
+end
+
+bot.run
+

data/examples/named-param-types.rb

@@ -0,0 +1,19 @@
+require 'cinch'
+
+bot = Cinch.setup do
+  server "irc.freenode.org"
+  channels %w( #cinch )
+end
+
+bot.plugin("say :n-digit :text") do |m|
+  m.args[:n].to_i.times {
+    m.reply m.args[:text]
+  }
+end
+
+bot.plugin("say :text-word :rest") do |m|
+  stuff = [m.args[:text], m.args[:rest]].join(' ')
+  m.reply stuff
+end
+
+bot.run

data/examples/seen.rb

@@ -0,0 +1,41 @@
+require 'cinch'
+
+users = {}
+
+class Seen < Struct.new(:who, :where, :what, :time)
+  def to_s
+    "[#{time.asctime}] #{who} was seen in #{where} saying #{what}"
+  end
+end
+
+bot = Cinch.setup(
+  :server => 'irc.freenode.org',
+  :channels => ['#cinch'],
+  :prefix => '!',
+  :verbose => true,
+)
+
+# Only log a PRIVMSG
+bot.on :privmsg do |m|
+  # Dont record a private message
+  unless m.private?
+    users[m.nick] = Seen.new(m.nick, m.channel, m.text, Time.new)
+  end
+end
+
+bot.plugin("seen :nick foo") do |m|
+  nick = m.args[:nick]
+
+  if nick == bot.nick
+    m.reply "That's me!"
+  elsif nick == m.nick
+    m.reply "That's you!"
+  elsif users.key?(nick)
+    m.reply users[nick].to_s
+  else
+    m.reply "I haven't seen #{nick}"
+  end
+end
+
+bot.run
+

data/lib/cinch.rb

@@ -5,10 +5,11 @@ require 'ostruct'
 require 'optparse'
 
 require 'cinch/irc'
+require 'cinch/rules'
 require 'cinch/base'
 
 module Cinch
-  VERSION = '0.1'
+  VERSION = '0.2'
 
   # Setup bot options and return a new Cinch::Base instance
   def self.setup(ops={}, &blk)

data/lib/cinch/base.rb

@@ -60,7 +60,7 @@ module Cinch
       options = DEFAULTS.merge(ops).merge(Options.new(&blk))
       @options = OpenStruct.new(options.merge(cli_ops))
 
-      @rules = {}
+      @rules = Rules.new
       @listeners = {}
 
       @irc = IRC::Socket.new(options[:server], options[:port])
@@ -85,12 +85,15 @@ module Cinch
             op.on("-n nick") {|v| options[:nick] = v }
             op.on("-c command_prefix") {|v| options[:prefix] = v }
             op.on("-v", "--verbose", "Enable verbose mode") {|v| options[:verbose] = true }
-            op.on("-j", "--channels x,y,z", Array, "Autojoin channels") {|v| 
+            op.on("-C", "--channels x,y,z", Array, "Autojoin channels") {|v| 
               options[:channels] = v.map {|c| %w(# + &).include?(c[0].chr) ? c : c.insert(0, '#') } 
             }
           end.parse(ARGV)
         rescue OptionParser::MissingArgument => err
-         warn "Missing values for options: #{err.args.join(', ')}\nFalling back to default"
+          warn "Missing values for options: #{err.args.join(', ')}\nFalling back to default"
+        rescue OptionParser::InvalidOption => err
+          warn err.message
+          exit
         end
       end
       options
@@ -104,7 +107,13 @@ module Cinch
     #  end
     def plugin(rule, options={}, &blk)
       rule, keys = compile(rule)
-      add_rule(rule, keys, options, &blk)
+      
+      if @rules.has_rule?(rule)
+        @rules.add_callback(rule, blk)
+        @rules.merge_options(rule, options)
+      else
+        @rules.add_rule(rule, keys, options, blk)
+      end
     end
     
     # Add new listeners
@@ -123,35 +132,80 @@ module Cinch
       end
     end
 
-    # Compile a rule string into regexp
+    # This method builds a regular expression from your rule
+    # and defines all named parameters, as well as dealing with 
+    # types.
+    #
+    # So far 3 types are supported:
+    #
+    # * word - matches [a-zA-Z]+
+    # * string - matches \w+
+    # * digit - matches \d+
+    #
+    # == Examples
+    # For capturing individual words
+    #  bot.plugin("say :text-word")
+    # * Does match !say foo
+    # * Does not match !say foo bar baz
+    #
+    # For capturing digits
+    #  bot.plugin("say :text-digit")
+    # * Does match !say 3
+    # * Does not match !say 3 4
+    # * Does not match !say foo
+    #
+    # For both
+    #  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
+    #  bot.plugin("say :text")
+    # * Does match !say foo
+    # * Does match !say foo bar
+    #
+    # Or mix them all
+    #  bot.plugin("say :n-digit :who-word :text")
+    #  
+    # Using "!say 3 injekt some text here" would provide
+    # the following attributes
+    # m.args[:n] => 3
+    # m.args[:who] => injekt
+    # m.args[:text] => some text here
     def compile(rule)
-      return [rule []] if rule.is_a?(Regexp)
+      return [rule, []] if rule.is_a?(Regexp)
       keys = []
       special_chars = %w{. + ( )}
 
-      pattern = rule.to_s.gsub(/((:\w+)|[\*#{special_chars.join}])/) do |match|
+      pattern = rule.to_s.gsub(/((:[\w\-]+)|[\*#{special_chars.join}])/) do |match|
         case match
         when *special_chars
           Regexp.escape(match)
         else
-          keys << $2[1..-1]
-          "([^\x00\r\n]+?)"
+          k = $2
+          if k =~ /\-(\w+)$/
+            key, type = k.split('-')
+            keys << key[1..-1]
+            
+            case type
+            when 'digit'; "(\\d+?)"
+            when 'word'; "([a-zA-Z]+?)"
+            when 'string'; "(\\w+?)"
+            else
+              "([^\x00\r\n]+?)"
+            end
+          else  
+            keys << k[1..-1]
+            "([^\x00\r\n]+?)"
+          end
         end
       end
       ["^#{pattern}$", keys]
     end
 
-    # Add a new rule, or add to an existing one if it
-    # already exists
-    def add_rule(rule, keys, options={}, &blk)
-      unless @rules.key?(rule)
-        @rules[rule] = [rule, keys, options, blk]
-      end
-    end
-
     # Run run run
-    def run
-      @irc.connect
+    def run      
+      @irc.connect options.server, options.port
       @irc.nick options.nick
       @irc.user options.username, options.usermode, '*', options.realname
         
@@ -166,6 +220,7 @@ module Cinch
 
     # Process the next line read from the server
     def process(line)
+      return unless line
       message = @parser.parse(line)
       message.irc = @irc
       puts message if options.verbose
@@ -175,40 +230,21 @@ module Cinch
       end
 
       if [:privmsg].include?(message.symbol)
-        rules.each_value do |attr|
-          rule, keys, ops, blk = attr
-          args = {}
-
-          unless ops.has_key?(:prefix) || options.prefix == false
-            rule.insert(1, options.prefix) unless rule[1].chr == options.prefix
+        rules.each do |rule|
+          unless rule.options.key?(:prefix) || options.prefix == false
+            rule.to_s.insert(1, options.prefix) unless rule.to_s[1].chr == options.prefix
           end
 
-          if message.text && mdata = message.text.match(Regexp.new(rule))
-            unless keys.empty? || mdata.captures.empty?
-              args = Hash[keys.map {|k| k.to_sym}.zip(mdata.captures)]
+          if message.text && mdata = message.text.match(Regexp.new(rule.to_s))
+            unless rule.keys.empty? || mdata.captures.empty?
+              args = Hash[rule.keys.map {|k| k.to_sym}.zip(mdata.captures)]
               message.args = args
-            end 
-            execute_rule(message, ops, blk)
-          end
-        end
-      end
-    end
-
-    # Execute a rule
-    def execute_rule(message, ops, blk)
-      ops.keys.each do |k|
-        case k
-        when :nick; return unless ops[:nick] == message.nick
-        when :user; return unless ops[:user] == message.user 
-        when :host; return unless ops[:host] == message.host
-        when :channel
-          if message.channel
-            return unless ops[:channel] == message.channel
+            end
+            # execute rule
+            rule.execute(message)
           end
         end
       end
-
-      blk.call(message)    
     end
 
     # Catch methods

data/lib/cinch/irc/parser.rb

@@ -80,7 +80,7 @@ module Cinch
       # Parse the incoming raw IRC string and return
       # a nicely formatted IRC::Message
       def parse_servermessage(raw)
-        raise ArgumentError, raw unless matches = raw.match(pattern(:message))
+        raise ArgumentError, raw unless raw && matches = raw.match(pattern(:message))
 
         prefix, command, parameters = matches.captures
 

data/lib/cinch/irc/socket.rb

@@ -87,8 +87,11 @@ module Cinch
       
       # Connect to an IRC server, returns true on a successful connection, or
       # raises otherwise
-      def connect
-        @socket = TCPSocket.new(server, port)
+      def connect(server=nil, port=nil)
+        @server = server if server
+        @port = port if port
+
+        @socket = TCPSocket.new(@server, @port)
       rescue Interrupt
         raise
       rescue Exception

data/lib/cinch/rules.rb

@@ -0,0 +1,161 @@
+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
+  # of options, and an Array of callbacks. 
+  #
+  # When a rule matches an IRC message, all options with be checked, then all
+  # callbacks will be invoked.
+  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
+    def execute(message)
+      options.keys.each do |key|
+        case key
+        when :nick
+          return unless options[:nick] == message.nick
+        when :host
+          return unless options[:host] == message.host
+        when :user
+          return unless options[:user] == message.user
+        when :channel
+          if message.channel
+            return unless options[:channel] == message.channel
+          end
+        end
+      end
+
+      callbacks.each do |blk|
+        blk.call(message)
+      end
+    end
+
+    # The rule as a String
+    def to_s
+      rule
+    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 
+  # method, or an alias of these. 
+  #
+  # This class provides an easy way to add options or callbacks to an existing
+  # rule.
+  #
+  # Essentially the add_callback, add_option, and merge_options methods are just sugar
+  # so you don't have to edit Rule attributes directly
+  #
+  # == Example
+  #  rules = Cinch::Rules.new
+  #
+  #  rules.add('foo', [], {}, Proc.new{})
+  #
+  #  rules.add_callback('foo', Proc.new{})
+  #  rules['foo'].callbacks #=> [#<Proc:0x9f1e110@(main):100>, #<Proc:0x9f1e0f4@(main):150>]
+  #
+  #  # Or assign directly
+  #  rules.get('foo').callbacks << Proc.new {} 
+  #
+  #  rules['foo'].options #=> {}
+  #  rules.add_option('foo', :nick, 'injekt')
+  #  rules['foo'].options #=> {:nick => 'injekt'}
+  #
+  #  # Or retrieve the rule first and assign directly
+  #  rules.get_rule('foo')
+  #  rules.options = {:foo => 'bar'}
+  #  rules.options[:bar] = 'baz'
+  class Rules
+    def initialize
+      @rules = {}
+    end
+
+    # Add a new rule, overwrites an already existing rule
+    def add_rule(rule, keys, options, callback)
+      @rules[rule] = Rule.new(rule, keys, options, callback) 
+    end
+    alias :add :add_rule
+
+    # Return a Cinch::Rule by its rule, or nil it one does not exist
+    def get_rule(rule)
+      @rules[rule]
+    end
+    alias :get :get_rule
+    alias :[] :get_rule
+
+    # Remove a rule
+    def remove_rule(rule)
+      @rules.delete(rule)
+    end
+    alias :remove :remove_rule
+
+    # Check if a rule exists
+    def include?(rule)
+      @rules.key?(rule)
+    end
+    alias :has_rule? :include?
+
+    # Add a callback for an already existing rule
+    def add_callback(rule, blk)
+      return unless include?(rule)
+      @rules[rule].callbacks << blk
+    end
+
+    # Add an option for an already existing rule
+    def add_option(rule, key, value)
+      return unless include?(rule)
+      @rules[rule].options[key] = value
+    end
+
+    # Merge rule options
+    def merge_options(rule, ops={})
+      return unless include?(rule)
+      @rules[rule].options.merge!(ops)
+    end
+
+    # Iterate over the rules
+    def each
+      @rules.each {|rule, obj| yield obj }
+    end
+
+    # Remove all rules
+    def clear
+      @rules.clear
+    end
+
+    # Check if any rules exist
+    def empty?
+      @rules.empty?
+    end
+
+    # Return how many rules exist
+    def count
+      @rules.size
+    end
+    alias :size :count
+
+    # Return the hash of rules
+    def all
+      @rules
+    end
+
+    # Return an Array of rules
+    def to_a
+      @rules.keys
+    end
+  end
+
+end
+

data/spec/base_spec.rb

@@ -0,0 +1,107 @@
+require File.dirname(__FILE__) + '/helper'
+
+describe "Cinch::Base" do
+  before do
+    @base = Cinch::Base.new
+
+    @full = Cinch::Base.new(
+      :server => 'irc.freenode.org',
+      :nick => 'CinchBot',
+      :channels => ['#cinch']
+    )
+  end
+
+  describe "::new" do 
+    it "should add a default ping listener" do
+      @base.listeners.should include :ping
+    end
+
+    it "should add a 376 listener, only if channels are set" do
+      @base.listeners.should_not include :'376'
+      @full.listeners.should include :'376'
+    end
+  end
+
+  describe "#plugin" do 
+    it "should compile and add a rule" do
+      @base.plugin('foo')
+      @base.rules.include?("^foo$").should == true
+    end
+
+    it "should add options to an existing rule" do
+      @base.plugin('foo') { }
+      @base.plugin('foo', :bar => 'baz') { }
+      rule = @base.rules.get('^foo$')
+      rule.options.should include :bar
+    end 
+
+    it "should add its block to an existing rule" do
+      @base.plugin('foo') { }
+      @base.plugin('foo') { }
+      rule = @base.rules.get_rule('^foo$')
+      rule.callbacks.size.should == 2
+    end
+  end
+
+  describe "#on" do
+    it "should save a listener" do
+      @base.on(:foo) {}
+      @base.listeners.should include :foo
+    end
+
+    it "should store listener blocks in an Array" do
+      @base.listeners[:ping].should be_kind_of Array
+    end
+  end
+
+  describe "#compile" do
+    it "should return an Array of 2 values" do
+      ret = @base.compile("foo")
+      ret.should be_kind_of(Array)
+      ret.size.should == 2
+    end
+    
+    it "should return an empty set of keys if no named parameters are labeled" do
+      rule, keys = @base.compile("foo")
+      keys.should be_empty
+    end
+
+    it "should return a key for each named parameter labeled" do
+      rule, keys = @base.compile("foo :bar :baz")
+      keys.size.should == 2
+      keys.should include "bar"
+      keys.should include "baz"
+    end
+
+    it "should return a rule of type String, unless Regexp is given" do
+      rule, keys = @base.compile(:foo)
+      rule.should be_kind_of(String)
+
+      rule, keys = @base.compile(/foo/)
+      rule.should be_kind_of(Regexp)
+      keys.should be_empty
+    end
+
+    it "should convert a digit type" do
+      rule, keys = @base.compile(":foo-digit")
+      rule.should == "^(\\d+?)$"
+    end
+
+    it "should convert a string type" do
+      rule, keys = @base.compile(":foo-string")
+      rule.should == "^(\\w+?)$"
+    end
+
+    it "should convert a word type" do
+      rule, keys = @base.compile(":foo-word")
+      rule.should == "^([a-zA-Z]+?)$"
+    end
+
+    it "should automatically add start and end anchors" do
+      rule, keys = @base.compile("foo bar baz")
+      rule[0].chr.should == "^"
+      rule[-1].chr.should == "$"
+    end
+  end
+end
+

data/spec/rules_spec.rb

@@ -0,0 +1,109 @@
+require File.dirname(__FILE__) + '/helper'
+
+describe "Cinch::Rules" do
+  before do
+    @rules = Cinch::Rules.new
+    @rules.add_rule('foo', [], {}, Proc.new{})
+  end
+
+  describe "::new" do
+    it "should define an empty set of rules" do
+      Cinch::Rules.new.empty?.should == true
+    end
+  end
+
+  describe "#add_rule" do
+    it "should add a new rule" do
+      @rules.add_rule('bar', [], {}, Proc.new{})
+      @rules.all.should include 'foo'
+    end
+
+    it "should replace an existing rule" do
+      @rules.add_rule('foo', [], {}, Proc.new{})
+      @rules.count.should == 1
+    end
+  end
+
+  describe "#get_rule" do
+    it "should return a Cinch::Rule" do
+      @rules.get_rule('foo').should be_kind_of Cinch::Rule
+    end
+  end
+
+  describe "#remove_rule" do
+    it "should remove a rule" do
+      @rules.remove_rule('foo')
+      @rules.include?('foo').should == false
+      @rules.count.should == 0
+    end
+  end
+
+  describe "#add_callback" do
+    it "should add a callback for a rule" do
+      @rules.add_callback('foo', Proc.new{})
+      rule = @rules.get_rule('foo')
+      rule.callbacks.size.should == 2
+    end
+  end
+
+  describe "#add_option" do
+    it "should add an option for a rule" do
+      @rules.add_option('foo', :nick, 'injekt')
+      rule = @rules.get('foo')
+      rule.options.should include :nick
+      rule.options[:nick].should == 'injekt'
+    end
+  end
+
+  describe "#merge_options" do
+    it "should merge rule options" do
+      @rules.merge_options('foo', {:bar => 'baz'})
+      rule = @rules['foo']
+      rule.options.should == {:bar => 'baz'}
+    end
+  end
+
+  describe "#include?" do
+    it "should check if a rule exists" do
+      @rules.include?('foo').should == true
+    end
+  end
+
+  describe "#clear" do
+    it "should clear all rules" do
+      @rules.clear
+      @rules.empty?.should == true
+    end
+  end
+
+  describe "#empty?" do
+    it "should check if any rules exist" do
+      @rules.empty?.should == false
+      @rules.clear
+      @rules.empty?.should == true
+    end
+  end
+
+  describe "#count" do
+    it "should show how many rules exist" do
+      @rules.count.should == 1
+      @rules.add_rule('bar', [], {}, Proc.new{})
+      @rules.count.should == 2
+    end
+  end
+
+  describe "#all" do
+    it "should return a Hash of all rules" do
+      @rules.all.should be_kind_of Hash
+      @rules.all.should include 'foo'
+    end
+  end
+
+  describe "#to_a" do
+    it "should return an Array of rules" do
+      @rules.to_a.should be_kind_of Array
+      @rules.to_a.include?('foo').should == true
+    end
+  end
+end
+

metadata

@@ -4,8 +4,8 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  version: "0.1"
+  - 2
+  version: "0.2"
 platform: ruby
 authors: 
 - Lee 'injekt' Jarvis
@@ -13,7 +13,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-25 00:00:00 +01:00
+date: 2010-04-26 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,18 +41,26 @@ extra_rdoc_files:
 files: 
 - README.rdoc
 - Rakefile
+- spec/base_spec.rb
 - spec/irc/socket_spec.rb
 - spec/irc/helper.rb
 - spec/irc/message_spec.rb
 - spec/irc/parser_spec.rb
 - spec/helper.rb
+- spec/rules_spec.rb
 - spec/options_spec.rb
 - lib/cinch.rb
 - lib/cinch/base.rb
 - lib/cinch/irc/message.rb
 - lib/cinch/irc/socket.rb
 - lib/cinch/irc/parser.rb
+- lib/cinch/rules.rb
 - lib/cinch/irc.rb
+- examples/join_part.rb
+- examples/msg.rb
+- examples/seen.rb
+- examples/hello.rb
+- examples/named-param-types.rb
 has_rdoc: true
 homepage: http://rdoc.injekt.net/cinch
 licenses: []