isaac 0.0.2

data/LICENSE

@@ -0,0 +1,6 @@
+------------------------------------------------------------------------------
+"THE BEER-WARE LICENSE" (Revision 42):
+<ichverstehe@gmail.com> wrote this file. As long as you retain this notice you
+can do whatever you want with this stuff. If we meet some day, and you think
+this stuff is worth it, you can buy me a beer in return.
+------------------------------------------------------------------------------

data/README.rdoc

@@ -0,0 +1,94 @@
+= Isaac - the smallish DSL for writing IRC bots
+You want to create an IRC bot quickly? Then Isaac is you. It will be. At some point, at least. But you shall be welcome to try it out and help me extend and beautify it. Be aware, the code is not stellar by any measure, most likely it is very crude and a large portion of the IRC standard has not been implemented, simply because I haven't needed it yet. Oh, and a lot of concepts were borrowed from Sinatra (http://sinatrarb.com). Thanks.
+
+== Features
+* Wraps parsing of incoming messages and raw IRC commands in simple constructs.
+* Hides all the ugly regular expressions of matching IRC commands. Leaves only the essentials for you to match.
+* Takes care of dull stuff such as replying to PING-messages and avoiding excess flood.
+
+== Getting started
+An Isaac-bot needs a few basics:
+  require 'isaac'
+  config do |c|
+    c.nick    = "AwesomeBot"
+    c.server  = "irc.freenode.net"
+    c.port    = 6667
+  end
+That's it. Run <tt>ruby bot.rb</tt> and it will connect to the specified server.
+
+=== Connecting
+After the bot has connected to the IRC server you might want to join some channels:
+  on :connect do
+    join "#awesome_channel", "#WesternBar"
+  end
+
+=== Responding to messages
+Joining a channel and sitting idle is not much fun. Let's repeat everything being said in these channels:
+
+  on :channel, /.*/ do
+    msg channel, message
+  end
+
+Notice the +channel+ and +message+ variables. Additionally +nick+ and +match+ is available for channel-events. +nick+ being the sender of the message, +match+ being a MatchData object returned by the regular expression you specified:
+
+  on :channel, /^quote this: (.*)/ do
+    msg channel, "Quote: '#{match[1]}' by #{nick}"
+  end
+
+If you want to match private messages use the +on :private+ event:
+
+  on :private, /^login (\S+) (\S+)/ do
+    username = match[1]
+    password = match[2]
+    # do something to authorize or whatevz.
+    msg nick, "Login successful!"
+  end
+
+=== Defining helpers
+Helpers should not be defined in the top level, but instead using the +helpers+-constructor:
+
+  helpers do
+    def rain_check(meeting)
+      msg nick, "Can I have a rain check on the #{meeting}?"
+    end
+  end
+
+  on :private, /date/ do
+    rain_check("romantic date")
+  end
+
+=== Errors, errors, errors
+Errors, as specified by RFC 1459, can be reacted upon as well. If you e.g. try to send a message to a non-existant nick you will get error 401: "No such nick/channel".
+
+  on :error, 401 do
+    # Do something.
+  end
+
+Available variables: +nick+ and +channel+.
+
+=== Send commands from outside an event
+You might want to send messages, join channels etc. without it strictly being the result of an on()-event, e.g. send a message every time a RSS feed is updated or whatever. You can use +Isaac.execute+ for that, and all your normal commands, +msg+, +join+, +topic+ etc. will be available:
+
+  class K
+    def smoke(brand)
+      Isaac.execute { msg "harryjr", "you should smoke #{brand} cigarettes" }
+    end
+  end
+
+  on :connect do
+    k = K.new
+    k.smoke("Lucky Strike")
+  end
+
+== Contribute
+The source is hosted at GitHub: http://github.com/ichverstehe/isaac
+
+== License
+  ------------------------------------------------------------------------------
+  "THE BEER-WARE LICENSE" (Revision 42):
+  <ichverstehe@gmail.com> wrote this file. As long as you retain this notice you
+  can do whatever you want with this stuff. If we meet some day, and you think
+  this stuff is worth it, you can buy me a beer in return.
+  ------------------------------------------------------------------------------
+
+

data/isaac.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |s|
+  s.name     = "isaac"
+  s.version  = "0.0.2"
+  s.date     = "2008-11-15"
+  s.summary  = "The smallish DSL for writing IRC bots"
+  s.email    = "ichverstehe@gmail.com"
+  s.homepage = "http://github.com/ichverstehe/isaac"
+  s.description = "Small DSL for writing IRC bots."
+  s.rubyforge_project = "isaac"
+  s.has_rdoc = true
+  s.authors  = ["Harry Vangberg"]
+  s.files    = ["README.rdoc", 
+    "LICENSE",
+		"isaac.gemspec", 
+		"lib/isaac.rb"]
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.extra_rdoc_files = ["LICENSE", "README.rdoc"]
+end

data/lib/isaac.rb

@@ -0,0 +1,245 @@
+require 'socket'
+module Isaac
+  # Returns the current instance of Isaac::Application
+  def self.app
+    @app ||= Application.new
+  end
+
+  # Use EventContext methods such as msg(), join() etc. outside on()-events. See +examples/execute.rb+.
+  #   Isaac.execute do
+  #     msg 'harryjr', 'you're awesome'
+  #   end
+  def self.execute(params={}, &block)
+    app.execute(params, &block)
+  end
+
+  Config = Struct.new(:nick, :server, :port, :username, :realname, :verbose)
+
+  # These are top level methods you use to construct your bot.
+  class Application
+    def initialize #:nodoc:
+      @events = Hash.new {|k,v| k[v] = []}
+    end
+
+    # This is plain stupid. Might be useful for logging or something later on.
+    def start #:nodoc:
+      puts " ==== Starting Isaac ==== "
+      loop { connect }
+      puts " ====  Ending Isaac  ==== "
+    end
+
+    # Configure the bot:
+    #   config do |c|
+    #     c.server    = "irc.freenode.net"
+    #     c.nick      = "AwesomeBot"
+    #     c.port      = 6667
+    #     c.realname  = "James Dean"
+    #     c.username  = "jdean"
+    #     c.verbose   = true
+    #   end
+    def config(&block)
+      @config = Config.new('isaac_bot', 'irc.freenode.net', 6667, 'isaac', 'isaac', false)
+      block.call(@config)
+      @config
+    end
+
+    # Methods defined inside the helpers-block will be available to on()-events at execution time.
+    def helpers(&block)
+      EventContext.class_eval(&block)
+    end
+
+    # on()-events responds to certain actions. Depending on +type+ certain local variables are available: +nick+, +channel+, +message+ and in particular +match+, which contains a MatchData object returned by the given regular expression.
+    #
+    # * Do something after connection has been established, e.g. join channels.
+    #     on :connect do
+    #       join "#awesome_channel", "#lee_marvin_fans"
+    #     end
+    # * Respond to private messages matching a given regular expression.
+    #     on :private, /^echo (.*)/ do
+    #       msg nick, "You said '#{match[1]}!"
+    #     end
+    # * Respond to messages matching a given regular expression send to a channel.
+    #     on :channel, /quote/ do
+    #       msg channel, "#{nick} requested a quote: 'Smoking, a subtle form a suicide.' - Vonnegut"
+    #     end
+    # * Respond to error codes, according to the RFC.
+    #     on :error, 401 do
+    #       # Execute this if you try to send a message to a non-existing nick/channel.
+    #     end
+    def on(type, match=nil, &block)
+      @events[type] << e = Event.new(match, block)
+      return e
+    end
+
+    def execute(params={}, &block) #:nodoc:
+      event = Event.new(:dsl, block)
+      @queue << event.invoke(params)
+    end
+
+    def event(type, matcher)
+      @events[type].detect do |e| 
+        type == :error ? matcher == e.match : matcher =~ e.match
+      end
+    end
+
+    def connect
+      begin
+        puts "Connecting to #{@config.server} at port #{@config.port}"
+        @irc = TCPSocket.open(@config.server, @config.port)
+        puts "Connection established."
+
+        @queue = Queue.new(@irc)
+        @queue << "NICK #{@config.nick}"
+        @queue << "USER #{@config.username} foobar foobar :#{@config.realname}"
+        @queue << @events[:connect].first.invoke if @events[:connect].first
+
+        while line = @irc.gets
+          handle line
+        end
+      rescue Interrupt => e
+        puts "Disconnected! An error occurred: #{e.inspect}"
+      rescue Timeout::Error => e
+        puts "Timeout: #{e}"
+      end
+    end
+
+    # This is one hell of a nasty method. Something should be done, I suppose.
+    def handle(line)
+      puts "< #{line}" if @config.verbose
+
+      case line
+      when /^:(\S+)!(\S+) PRIVMSG (\S+) :?(.*)/
+        nick, userhost, channel, message = $1, $2, $3, $4
+        type = channel.match(/^#/) ? :channel : :private
+        if event = event(type, message)
+          @queue << event.invoke(:nick => nick, :userhost => userhost, :channel => channel, :message => message)
+        end
+      when /^:\S+ ([4-5]\d\d) \S+ (\S+)/
+        error = $1
+        nick = channel = $2
+        if event = event(:error, error.to_i)
+          @queue << event.invoke(:nick => nick, :channel => channel)
+        end
+      when /^PING (\S+)/
+        #TODO not sure this is correct. Damned RFC.
+        @queue << "PONG #{$1}" 
+      when /^:\S+ PONG \S+ :excess/
+        @queue.lock = false
+      end
+    end
+  end
+  
+  class Queue #:nodoc:
+    attr_accessor :lock
+    def initialize(socket)
+      @socket     = socket
+      @queue      = []
+      @transfered = 0
+      @lock       = false
+      transmit
+    end
+
+    # I luvz Rubyz
+    def << (msg)
+      # .flatten! returns nill if no modifications were made, thus we do this. 
+      @queue = (@queue << msg).flatten
+    end
+
+    # To prevent excess flood no more than 1472 bytes will be sent to the
+    # server. When that limit is reached, @lock = true and the server will be
+    # PINGed. @lock will be true until a PONG is received (Application#handle).
+    def transmit
+      Thread.start { loop {
+        unless @lock || @queue.empty?
+          msg = @queue.shift
+          if (@transfered + msg.size) > 1472
+            # No honestly, :excess. The RFC is not too clear on this subject TODO
+            @socket.puts "PING :excess"
+            @lock = true
+            @transfered = 0
+          else
+            @socket.puts msg
+            @transfered += msg.size
+          end
+        end
+        sleep 0.1
+      }}
+    end
+  end
+
+  class Event #:nodoc:
+    attr_accessor :match, :block
+    def initialize(match, block)
+      @match    = match
+      @block    = block
+    end
+
+    # Execute event in the context of EventContext.
+    def invoke(params={})
+      match = params[:message].match(@match) if @match && params[:message]
+      params.merge!(:match => match)
+
+      context = EventContext.new(params)
+      context.instance_eval(&@block)
+      context.commands
+    end
+  end
+
+  class EventContext
+    attr_accessor :nick, :userhost, :channel, :message, :match, :commands
+    def initialize(args = {})
+      args.each {|k,v| instance_variable_set("@#{k}",v)}
+      @commands = []
+    end
+
+    # Send a raw IRC message.
+    def raw(command)
+      @commands << command
+    end
+
+    # Send a message to nick/channel.
+    def msg(recipient, text)
+      raw("PRIVMSG #{recipient} :#{text}")
+    end
+
+    # Join channel(s):
+    #   join "#awesome_channel"
+    #   join "#rollercoaster", "#j-lo"
+    def join(*channels)
+      channels.each {|channel| raw("JOIN #{channel}")}
+    end
+
+    # Part channel(s):
+    #   part "#awesome_channel"
+    #   part "#rollercoaster", "#j-lo"
+    def part(*channels)
+      channels.each {|channel| raw("PART #{channel}")}
+    end
+
+    # Kick nick from channel, with optional comment.
+    def kick(channel, nick, comment=nil)
+      comment = " :#{comment}" if comment
+      raw("KICK #{channel} #{nick}#{comment}")
+    end
+
+    # Change topic of channel.
+    def topic(channel, topic)
+      raw("TOPIC #{channel} :#{topic}")
+    end
+  end
+end
+
+# Assign methods to current Isaac instance
+%w(config helpers on).each do |method|
+  eval(<<-EOF)
+    def #{method}(*args, &block)
+      Isaac.app.#{method}(*args, &block)
+    end
+  EOF
+end
+
+# Clever, thanks Sinatra.
+at_exit do
+  raise $! if $!
+  Isaac.app.start
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+name: isaac
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Harry Vangberg
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-15 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Small DSL for writing IRC bots.
+email: ichverstehe@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- README.rdoc
+- LICENSE
+- isaac.gemspec
+- lib/isaac.rb
+has_rdoc: true
+homepage: http://github.com/ichverstehe/isaac
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: isaac
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: The smallish DSL for writing IRC bots
+test_files: []
+