cinch 0.1

data/README.rdoc

@@ -0,0 +1,120 @@
+= Cinch: The IRC Microframework
+
+== Description
+
+Cinch is an IRC Microframework 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.
+
+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.
+
+== Installation
+
+=== RubyGems
+You can install the latest version of Cinch using RubyGems
+ gem install cinch
+
+=== GitHub
+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'
+
+ bot = Cinch.setup do
+   server "irc.freenode.org"
+   nick "Cinch"
+ end
+
+ bot.plugin "hello" do |m|
+   m.reply "Hello, #{m.nick}!"
+ end
+
+ bot.run
+
+It doesn't take much to work out what's happening here, but I'll explain it anyway.
+
+First we run the <em>Cinch::setup</em> block which is required in every application. Cinch is boxed
+with a load of default values, so the <b>only</b> option required in this block is the <em>server</em>
+option. We then define a plugin using the <em>plugin</em> method and pass it a rule (a String in this
+case). Every plugin must be mapped to a rule. When the rule matches an IRC message its block is
+invoked, the contents of which contains your plugin interface. The variable passed to the block is
+an instance of IRC::Message. This provides us with a couple of helper methods which can be used to
+reply to a message. See Cinch::IRC::Message#reply and Cinch::IRC::Message#answer
+
+This example would provide the following response on IRC:
+
+ * Cinch has joined #cinch
+ injekt> !hello
+ Cinch> Hello, injekt!
+
+Since Cinch doesn't provide a binary executable, running your application is as simple as you would any 
+other Ruby script. 
+
+ ruby hello.rb
+
+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
+
+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 (#) 
+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:
+
+ injekt> Cinch: hello
+ Cinch> Hello, injekt!
+
+Cinch also provides named parameters. This method of expression was inspired by the {Sinatra
+Web Framework}[http://www.sinatrarb.com/] and although it doesn't quite follow the same pattern,
+it's useful for naming parameters passed to plugins. These paramaters are available through the 
+Cinch::IRC::Message#args method which is passed to each plugin.
+
+ bot.plugin("say :text") do |m|
+   m.reply m.args[:text]
+ end
+
+This plugin would provide the following output:
+
+ injekt> !say foo bar baz
+ Cinch> foo bar baz
+
+Each plugin takes an optional hash of message specific options. These options provide an extension to
+the rules given, for example if we want to reply only if the nick sending the message is injekt, we
+could pass the 'nick' option to the hash.
+
+ bot.plugin("join :channel", :nick => 'injekt') do |m|
+   m.join #{m.args[:channel]}
+ end
+
+== Authors
+Just me at the moment, sad poor lonely me...
+* {Lee Jarvis}[http://blog.injekt.net]
+
+== Notes
+
+* RDoc API documentation is available {here}[http://rdoc.injekt.net/cinch]
+* Wiki is available {here}[https://github.com/injekt/cinch/wikis]
+* Issue and feature tracking is available {here}[https://github.com/injekt/cinch/issues]
+* Contribution in the form of bugfixes or feature requests is welcome and encouraged
+
+If you'd like to contribute, fork the GitHub repository, make any changes, and send 
+{injekt}[http://github.com/injekt] a pull request. Collaborator access is available on
+request once one patch has been submitted.
+
+== TODO
+* More specs
+* More documentation
+* More examples
+

data/Rakefile

@@ -0,0 +1,65 @@
+require "rake"
+require "rake/clean"
+require "rake/gempackagetask"
+require "rake/rdoctask"
+require "spec/rake/spectask"
+
+require 'lib/cinch'
+
+NAME = 'cinch'
+VERSION = Cinch::VERSION
+TITLE = "Cinch: The IRC Microframework"
+CLEAN.include ["*.gem", "rdoc"]
+RDOC_OPTS = [
+  "-U", "--title", TITLE,
+  "--op", "rdoc",
+  "--main", "README.rdoc"
+]
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.options += RDOC_OPTS
+  rdoc.rdoc_files.add %w(README.rdoc lib/**/*.rb)
+end
+
+desc "Package"
+task :package => [:clean] do |p|
+  sh "gem build #{NAME}.gemspec"
+end
+
+desc "Install gem"
+task :install => [:package] do
+  sh "sudo gem install ./#{NAME}-#{VERSION} --local"
+end
+
+desc "Uninstall gem"
+task :uninstall => [:clean] do
+  sh "sudo gem uninstall #{NAME}"
+end
+
+desc "Upload gem to gemcutter"
+task :release => [:package] do
+  sh "gem push ./#{NAME}-#{VERSION}.gem"
+end
+
+desc "Upload rdoc to injekt.net"
+task :upload => [:clean, :rdoc] do
+  sh("scp -r rdoc/* injekt@injekt.net:/var/www/injekt.net/rdoc/cinch")
+end
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = Dir['spec/**/*_spec.rb']
+end
+
+namespace :spec do
+  desc "Print with specdoc formatting"
+  Spec::Rake::SpecTask.new(:doc) do |t|
+    t.spec_opts = ["--format", "specdoc"]
+    t.spec_files = Dir['spec/**/*_spec.rb']
+  end
+end
+
+
+task :default => [:clean, :spec]
+

data/lib/cinch.rb

@@ -0,0 +1,19 @@
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(dir) unless $LOAD_PATH.include? dir
+
+require 'ostruct'
+require 'optparse'
+
+require 'cinch/irc'
+require 'cinch/base'
+
+module Cinch
+  VERSION = '0.1'
+
+  # Setup bot options and return a new Cinch::Base instance
+  def self.setup(ops={}, &blk)
+    Cinch::Base.new(ops, &blk)
+  end
+
+end
+

data/lib/cinch/base.rb

@@ -0,0 +1,236 @@
+module Cinch
+
+  # == Author
+  # * Lee Jarvis - ljjarvis@gmail.com
+  #
+  # == Description
+  # The base for an IRC connection
+  # TODO: More documentation
+  #
+  # == Example
+  #  bot = Cinch::Base.new :server => 'irc.freenode.org'
+  #
+  #  bot.on :join do |m|
+  #    m.reply "Welcome to #{m.channel}, #{m.nick}!" unless m.nick == bot.nick
+  #  end
+  #
+  #  bot.plugin "say :text" do |m|
+  #    m.reply m.args[:text]
+  #  end
+  class Base
+
+    # A Hash holding rules and attributes
+    attr_reader :rules
+    
+    # A Hash holding listeners and reply Procs
+    attr_reader :listeners
+
+    # An OpenStruct holding all configuration options
+    attr_reader :options
+
+    # Default options hash
+    DEFAULTS = {
+      :port => 6667,
+      :nick => "Cinch",
+      :username => 'cinch',
+      :realname => "Cinch IRC Microframework",
+      :prefix => '!',
+      :usermode => 0,
+    }
+
+    # Options can be passed via a hash, a block, or on the instance
+    # independantly. Or of course via the command line
+    #
+    # == Example
+    #  # With a Hash
+    #  bot = Cinch::Base.new(:server => 'irc.freenode.org')
+    #
+    #  # With a block
+    #  bot = Cinch::Base.new do
+    #    server "irc.freenode.org"
+    #  end
+    #
+    #  # After the instance is created
+    #  bot = Cinch::Base.new
+    #  bot.options.server = "irc.freenode.org"
+    #
+    #  # Nothing, but invoked with "ruby foo.rb -s irc.freenode.org"
+    #  bot = Cinch::Base.new
+    def initialize(ops={}, &blk)
+      options = DEFAULTS.merge(ops).merge(Options.new(&blk))
+      @options = OpenStruct.new(options.merge(cli_ops))
+
+      @rules = {}
+      @listeners = {}
+
+      @irc = IRC::Socket.new(options[:server], options[:port])
+      @parser = IRC::Parser.new
+
+      # Default listeners
+      on(:ping) {|m| @irc.pong(m.text) }
+      
+      if @options.respond_to?(:channels)
+        on(376) { @options.channels.each {|c| @irc.join(c) } }
+      end
+    end
+
+    # Parse command line options
+    def cli_ops
+      options = {}
+      if ARGV.any?
+        begin
+          OptionParser.new do |op|
+            op.on("-s server") {|v| options[:server] = v }
+            op.on("-p port") {|v| options[:port] = v.to_i }
+            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| 
+              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"
+        end
+      end
+      options
+    end
+
+    # Add a new plugin
+    #
+    # == Example
+    #  plugin('hello') do |m|
+    #    m.reply "Hello, #{m.nick}!"
+    #  end
+    def plugin(rule, options={}, &blk)
+      rule, keys = compile(rule)
+      add_rule(rule, keys, options, &blk)
+    end
+    
+    # Add new listeners
+    #
+    # == Example
+    #  on(376) do |m|
+    #    m.join "#mychan"
+    #  end
+    def on(*commands, &blk)
+      commands.map {|x| x.to_s.downcase.to_sym }.each do |cmd|
+        if @listeners.key?(cmd)
+          @listeners[cmd] << blk
+        else
+          @listeners[cmd] = [blk]
+        end
+      end
+    end
+
+    # Compile a rule string into regexp
+    def compile(rule)
+      return [rule []] if rule.is_a?(Regexp)
+      keys = []
+      special_chars = %w{. + ( )}
+
+      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]+?)"
+        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
+      @irc.nick options.nick
+      @irc.user options.username, options.usermode, '*', options.realname
+        
+      begin
+        process(@irc.read) while @irc.connected?
+      rescue Interrupt
+        @irc.quit("Interrupted")
+        puts "\nInterrupted. Shutting down.."
+        exit
+      end
+    end
+
+    # Process the next line read from the server
+    def process(line)
+      message = @parser.parse(line)
+      message.irc = @irc
+      puts message if options.verbose
+
+      if @listeners.key?(message.symbol)
+        @listeners[message.symbol].each {|l| l.call(message) }
+      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
+          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)]
+              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
+        end
+      end
+
+      blk.call(message)    
+    end
+
+    # Catch methods
+    def method_missing(meth, *args, &blk) # :nodoc:
+      if options.respond_to?(meth)
+        options.send(meth)
+      elsif @irc.respond_to?(meth)
+        @irc.send(meth, *args)
+      else
+        super
+      end
+    end
+
+    # Option management
+    class Options < Hash # :nodoc:
+      def initialize(&blk)
+        instance_eval(&blk) if block_given?
+      end
+      def method_missing(meth, *args, &blk)
+        self[meth] = args.first unless args.empty?
+      end
+    end
+  end
+end
+

data/lib/cinch/irc.rb

@@ -0,0 +1,44 @@
+lib = File.dirname(__FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'socket'
+
+require 'irc/parser'
+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.
+  #
+  # You can use these tools through Cinch or include them directly and use
+  # them on their own.
+  #
+  # Each class inside of this module can be used direcly as they contain
+  # no references to higher level classes inside Cinch
+  #
+  # == Example
+  #  require 'cinch/irc'
+  #  require 'pp'
+  #
+  #  parser = Cinch::IRC::Parser.new
+  #
+  #  Cinch::IRC::Socket.new('irc.2600.net') do |irc|
+  #    irc.nick "Cinch"
+  #    irc.user "Cinch", 0, '*', "Cinch IRC bot"
+  #
+  #    while line = irc.read
+  #      message = parser.parse(line)
+  #  
+  #      pp message
+  #    end
+  #  end
+  #
+  module IRC
+
+  end
+end