bbrowning-ponder 0.0.2.1

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2010, 2011 Tobias Bühlmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,334 @@
+# Ponder
+
+## Description
+Ponder (Stibbons) is a Domain Specific Language for writing IRC Bots using the [EventMachine](http://github.com/eventmachine/eventmachine "EventMachine") library.
+
+## Getting started
+### Installation
+    $ sudo gem install ponder
+
+### Configuring the Bot (Thaum!)
+    require 'rubygems'
+    require 'ponder'
+    
+    @ponder = Ponder::Thaum.new
+    
+    @ponder.configure do |c|
+      c.nick   = 'Ponder'
+      c.server = 'irc.freenode.net'
+      c.port   = 6667
+    end
+
+### Starting the Thaum
+    @ponder.connect
+
+### Event Handling
+This naked Thaum will connect to the server and answer PING requests (and VERSION and TIME). If you want the Thaum to join a channel when it's connected, use the following:
+
+    @ponder.on :connect do
+      @ponder.join '#mended_drum'
+    end
+
+If you want the Thaum to answer on specific channel messages, register this Event Handler:
+
+    @ponder.on :channel, /ponder/ do |event_data|
+      @ponder.message event_data[:channel], 'Heard my name!'
+    end
+
+Now, if an incoming channel message contains the word "ponder", the Thaum will send the message "Heard my name!" to that specific channel. See the **Advanced Event Handling** chapter for more details on how to register Event Handlers and the `event_data` hash. For more examples, have a look at the examples directory.
+
+## Advanced Configuration
+Besides the configuration for nick, server and port as shown in the **Getting Started** chapter, there are some more preferences Ponder accepts. All of them:
+
+* `server`
+
+    The `server` variable describes the server the Thaum shall connect to. It defaults to `'localhost'`.
+
+* `port`
+
+    `port` describes the port that is used for the connection. It defaults to `6667`.
+
+* `nick`
+
+    `nick` describes the nick the Thaum will try to register when connecting to the server. It will not be updated if the Thaum changes its nick. It defaults to `'Ponder'`.
+
+* `username`
+
+    `username` is used for describing the username. It defaults to `'Ponder'`.
+
+* `real_name`
+
+    `real_name` is used for describing the real name. It defaults to `'Ponder'`.
+
+* `verbose`
+
+    If `verbose` is set to `true`, all incoming and outgoing traffic will be put to the console. Plus exceptions raised in Callbacks (errors). It defaults to `true`.
+
+* `logging`
+
+    If `logging` is set to `true`, all incoming and outgoing traffic will be logged to logs/traffic.log and errors will be logged to logs/error.log. If you just want to log errors, you can manipulate the traffic logger in the configure block with `c.traffic_logger = c.empty_logger`. A logger set to `empty_logger` will not log anything.
+    
+    You can also define other loggers for traffic\_logger and error\_logger with `c.traffic_logger = @my_cool_logger` or `c.traffic_logger = Logger.new(...)`. Per default, there are just #info and #error called on the logger.
+    
+    You can access the logger instances via `@ponder.traffic_logger` or `@ponder.error_logger`, so you could do: `@ponder.traffic_logger.info('I did this and that right now')`.
+    
+    It defaults to `false`. (TODO: write about "other" logger methods)
+
+* `reconnect`
+
+    If `reconnect` is set to `true`, the Thaum will try to reconnect after being disconnected from the server (netsplit, ...). It will not try to reconnect if you call `quit` on the Thaum. It defaults to `true`.
+
+* `reconnect_interval`
+
+    If `reconnect` is set to `true`, `reconnect_interval` describes the time in seconds, which the Thaum will wait before trying to reconnect. It defaults to `30`.
+
+For further information, have a look at the examples.
+
+## Advanced Event Handling
+A Thaum can react on several events, so here is a list of handlers that can be used as argument in the `on` method:
+
+* `join`
+
+    The `join` handler reacts, if an user joins a channel in which the Thaum is in. Example:
+    
+        @ponder.on :join do
+          # ...
+        end
+        
+    If using a block variable, you have access to a hash with detailed information about the event. Example:
+    
+        @ponder.on :join do |event_data|
+          @ponder.message event_data[:channel], "Hello #{event_data[:nick]}! Welcome to #{event_data[:channel]}."
+        end
+    
+    Which will greet a joined user with a channel message.
+    
+    The hash contains data for the keys `:nick`, `:user`, `:host` and `:channel`.
+
+* `part`
+
+    Similar to the `join` handler but reacts on parting users. The block variable hash contains data for the keys `:nick`, `:user`, `:host`, `:channel` and `:message`. The value for `:message` is the message the parting user leaves.
+
+* `quit`
+
+    The `quit` handler reacts, if an user quits from the server (and the Thaum can see it in a channel). The block variable hash contains data for the keys `:nick`, `:user`, `:host` and `:message`.
+
+* `channel`
+
+    If an user sends a message to a channel, you can react with the `channel` handler. Example (from above):
+    
+        @ponder.on :channel, /ponder/ do |event_data|
+          @ponder.message event_data[:channel], 'Heard my name!'
+        end
+    
+    The block variable hash contains data for the keys `:nick`, `:user`, `:host`, `:channel` and `:message`.
+
+* `query`
+
+    The `query` handler is like the `channel` handler, but for queries. Same keys in the data hash but no `:channel`.
+
+* `nickchange`
+
+    `nickchange` reacts on nickchanges. Data hash keys are `:nick`, `:user`, `:host` and `:new_nick`, where `nick` is the nick before renaming and `new_nick` the nick after renaming.
+
+* `kick`
+
+    If an user is being kicked, the `kick` handler can handle that event. Data hash keys are: `:nick`, `:user`, `:host`, `:channel`, `:victim` and `:reason`.
+
+* `topic`
+
+    `topic` is for reacting on topic changes. Data hash keys are: `:nick`, `:user`, `:host`, `:channel` and `:topic`, where `:topic` is the new topic. You can provide a Regexp to just react on specific patterns:
+    
+        @ponder.on :topic, /foo/ do |event_data|
+          # ...
+        end
+    
+    This will just work for topics that include the word "foo".
+
+* `disconnect`
+
+    `disconnect` reacts on being disconnected from the server (netsplit, quit, ...). It does not react if you exit the program with ^C.
+
+* Raw numerics
+
+    A Thaum can seperately react on events with raw numerics, too. So you could do:
+    
+        @ponder.on 301 do |event_data|
+          # ...
+        end
+    
+    The data hash will contain the `:params` key. The corresponding value is the complete traffic line that came in.
+
+For all Event Handlers there is a `:type` key in the data hash (if the variable is specified). Its value gives the type of event, like `:channel`, `:join` or `301`.
+
+You can even share handler bodies between different events. So you are able to do something like this:
+
+    @ponder.on [:join, :part, :quit] do |event_data|
+      # ...
+    end
+
+or
+
+    @ponder.on [:channel, :query], /ponder/ do |event_data|
+      @ponder.message((event_data[:channel] || event_data[:nick]), 'Yes?')
+    end
+
+or
+
+    @ponder.on [:channel, :nickchange], /foo/ do |event_data|
+      # ...
+    end
+
+They are not really shared at all, Ponder will just copy the Callback, but it's comfortable.
+
+## Commanding the Thaum
+Command the Thaum, very simple. Just call a method listed below on the Ponder object. I will keep this short, since I assume you're at least little experienced with IRC.
+
+* `message(recipient, message)`
+* `notice(recipient, message)`
+* `mode(recipient, option)`
+* `kick(channel, user, reason = nil)`
+* `action(recipient, message)`
+* `topic(channel, topic)`
+* `join(channel, password = nil)`
+* `part(channel, message = nil)`
+* `quit(message = nil)`
+* `rename(nick)`
+* `away(message = nil)`
+* `back`
+* `invite(nick, channel)`
+* `ban(channel, address)`
+
+Last but not least some cool "give me something back" methods:
+
+* `get_topic(channel)`
+
+    * Possible return values for `get_topic` are:
+    
+        * `{:raw_numeric => 331, :message => 'No topic is set'}` if no topic is set
+        * `{:raw_numeric => 332, :message => message}` with `message` the topic message
+        * `{:raw_numeric => 403, :message => 'No such channel'}` if there is no such channel
+        * `{:raw_numeric => 442, :message => "You're not on that channel"}` if you cannot actually see the topic
+        * `false` if the request times out (30 seconds)
+
+* `channel_info(channel)`
+
+    * Possible return values:
+    
+        * If successful, a hash with keys:
+        
+            * `:modes` (letters)
+            * `:channel_limit` (if channel limit is set)
+            * `:created_at` (Time object of the time the channel was created)
+            
+        * `false`, if the request is not successful or times out (30 seconds)
+
+* `whois(nick)`
+
+    * Possible return values:
+    
+        * If successful, a hash with keys:
+        
+            * `:nick`
+            * `:username`
+            * `:host`
+            * `:real_name`
+            * `:server` (a hash with the keys `:address` and `:name`)
+            * `:channels` (a hash like `{'#foo' => '@', '#bar' => nil}` where the values are user privileges)
+            * `:registered` (`true`, if registered, else `nil`)
+            
+        * If not successful
+        
+            * `false`
+            
+        * If times out (30 seconds)
+        
+            * `nil`
+    
+    Example:
+    
+        # Ponder, kick an user (and check if I'm allowed to command you)!
+        @ponder.on :channel, /^!kick \S+$/ do |event_data|
+          user_data = @ponder.whois(event_data[:nick])
+          if user_data[:registered] && (user_data[:channels][event_data[:channel]] == '@')
+            user_to_kick = event_data[:message].split(' ')[1]
+            @ponder.kick event_data[:channel], user_to_kick, 'GO!'
+          end
+        end
+
+## Filters
+### Before Filters
+You can have Before Filters! They are called before each event handling process and can - among other things - manipulate the `event_data` hash. If a Before Filter returns `false`, no further filters (no After Filters either) are called and the event handling process won't fire up. Example:
+
+    @ponder.before_filter(:channel, /foo/) do
+      # ...
+    end
+
+This Before Filter will be called, if a channel message with the word "foo" gets in. You can use all other event types (like :query, :kick, ...) as well. Also possible is an array notation like `before_filter([:query, :channel], /foo/) ...`. If you want the filter to work an all event types, you can simply use `:all`. Filters will be called in defining order; first defined, first called. Event specific filters are called before `:all` filters.
+
+### After Filters
+After Filters work the same way as Before Filters do, just after the actual event handling process. An After Filter does not hinder later After Filters to fire up if it returns `false`. Example:
+
+    @ponder.after_filter(:all, //) do
+      # ...
+    end
+
+## Timers
+If you need something in an event handling process to be time-displaced, you should not use `sleep`. I recommend using the comfortable timer methods EventMachine provides. A one shot timer looks like this:
+
+    EventMachine::Timer.new(10) do
+      # code to be run after 10 seconds
+    end
+
+If you want the timer to be canceled before starting, you can do it like this:
+
+    timer = EventMachine::Timer.new(10) do
+      # code to be run after 10 seconds
+    end
+    
+    # ...
+    
+    timer.cancel
+
+You can even have periodic timers which will fire up every n seconds:
+
+    EventMachine::PeriodicTimer.new(10) do
+      # code to be run every 10 seconds
+    end
+
+A periodic timer can be canceled just like the other one.
+
+## Formatting
+You can format your messages with colors, make it bold, italic or underlined. All of those formatting constants are availabe through `Ponder::Formatting`.
+
+### Colors
+For coloring text you first set the color code with `Ponder::Formatting::COLOR_CODE` followed by a color followed by the text. For ending the colored text, set the uncolor code with `Ponder::Formatting::UNCOLOR`.
+
+Availabe colors are white, black, blue, green, red, brown, purple, orange, yellow, lime, teal, cyan, royal, pink, gray and silver. You can set one with the `Ponder::Formatting::COLORS` hash. Example:
+
+    "This will be #{Ponder::Formatting::COLOR_CODE}#{Ponder::Formatting::COLORS[:red]}red#{Ponder::Formatting::UNCOLOR_CODE}. This not."
+
+### Font Styles
+If you want to make a text bold, italic or underlined, use `Ponder::Formatting::BOLD`, `Ponder::Formatting::ITALIC` or `Ponder::Formatting::UNDERLINE`. After the text, close it with the same constant. Example:
+
+    "This will be #{Ponder::Formatting::UNDERLINE}underlined#{Ponder::Formatting::UNDERLINE}. This not."
+
+### Shortened Formatting
+If you don't always want to use `Ponder::Formatting`, use `include Ponder::Formatting`. All constants will then be availabe without `Ponder::Formatting` in front.
+
+## Source
+The source can be found at GitHub: [tbuehlmann/ponder](http://github.com/tbuehlmann/ponder "Ponder").
+
+You can contact me through [GitHub](http://github.com/tbuehlmann/ "GitHub") and IRC (named tbuehlmann in the Freenode network).
+
+## Discworld Context
+So, why all that silly names? Ponder Stibbons? Thaum? Twoflogger (referring to Twoflower), BlindIO? What's the Mended Drum? Who's the Librarian? Simply put, I freaking enshrine Terry Pratchett's Discworld Novels and there were no better name for this project than Ponder. Ponder Stibbons is the Head of Inadvisably Applied Magic at the Unseen University of Ankh Morpork. He researched the Thaum, like the atom, just for magic. And I just love that character, so there we are. If you're a fan too or want to talk about the Discworld, the framework, whatever, don't hesitate to contact me.
+
+## License
+Copyright (c) 2010, 2011 Tobias Bühlmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/examples/echo.rb

@@ -0,0 +1,25 @@
+require 'pathname'
+$LOAD_PATH.unshift Pathname.new(__FILE__).dirname.expand_path.join('..', 'lib')
+
+require 'ponder'
+
+# This Thaum will parrot all channel messages.
+@ponder = Ponder::Thaum.new
+
+@ponder.configure do |c|
+  c.server    = 'chat.freenode.org'
+  c.port      = 6667
+  c.nick      = 'Ponder'
+  c.verbose   = true
+  c.logging   = false
+end
+
+@ponder.on :connect do
+  @ponder.join '#ponder'
+end
+
+@ponder.on :channel, // do |event_data|
+  @ponder.message event_data[:channel], event_data[:message]
+end
+
+@ponder.connect

data/examples/github_blog.rb

@@ -0,0 +1,31 @@
+require 'pathname'
+$LOAD_PATH.unshift Pathname.new(__FILE__).dirname.expand_path.join('..', 'lib')
+
+require 'ponder'
+require 'rubygems'
+require 'nokogiri'
+require 'open-uri'
+
+# This Thaum answers the channel message "blog?" with the title of the newest github blog entry.
+@ponder = Ponder::Thaum.new
+
+@ponder.configure do |c|
+  c.server    = 'chat.freenode.org'
+  c.port      = 6667
+  c.nick      = 'Ponder'
+  c.verbose   = true
+  c.logging   = false
+end
+
+@ponder.on :connect do
+  @ponder.join '#ponder'
+end
+
+@ponder.on :channel, /^blog\?$/ do |event_data|
+  doc = Nokogiri::HTML(open('http://github.com/blog'))
+  title = doc.xpath('//html/body/div/div[2]/div/div/ul/li/h2/a')[0].text
+  
+  @ponder.message event_data[:channel], "Newest Github Blog Post: #{title}"
+end
+
+@ponder.connect

data/examples/redis_last_seen.rb

@@ -0,0 +1,140 @@
+# This Thaum remembers users' actions and is able to quote them.
+# Go for it with `!seen <nick>`. You can even use wildcards with "*".
+# 
+# The redis server version needs to be >= 1.3.10 for hash support.
+
+require 'pathname'
+$LOAD_PATH.unshift Pathname.new(__FILE__).dirname.expand_path.join('..', 'lib')
+require 'ponder'
+require 'rubygems'
+require 'redis'
+
+FORMAT = '%Y-%m-%d %H:%M:%S'
+
+class String
+  def escape_redis
+    self.gsub(/([\|\[\]\?])/, '\\\\\1')
+  end
+end
+
+@last_seen = Redis.new(:thread_safe => true)
+
+def remember(lowercase_nick, nick, user, host, channel, action,
+               action_content)
+  @last_seen.hmset(lowercase_nick,
+                     'nick',           nick,
+                     'user',           user,
+                     'host',           host,
+                     'channel',        channel,
+                     'action',         action,
+                     'action_content', action_content,
+                     'updated_at',     Time.now.to_i)
+end
+
+@ponder = Ponder::Thaum.new
+
+@ponder.configure do |c|
+  c.server    = 'chat.freenode.org'
+  c.port      = 6667
+  c.nick      = 'Ponder'
+  c.verbose   = true
+  c.logging   = false
+end
+
+@ponder.on :connect do
+  @ponder.join '#ponder'
+end
+
+@ponder.on :channel do |event_data|
+  remember(event_data[:nick].downcase, event_data[:nick], event_data[:user],
+             event_data[:host], event_data[:channel], event_data[:type],
+             event_data[:message])
+end
+
+@ponder.on [:join, :part, :quit] do |event_data|
+  remember(event_data[:nick].downcase, event_data[:nick], event_data[:user],
+             event_data[:host], event_data[:channel], event_data[:type],
+             (event_data[:message] || event_data[:channel]))
+end
+
+@ponder.on :nickchange do |event_data|
+  remember(event_data[:nick].downcase, event_data[:nick], event_data[:user],
+             event_data[:host], '', 'nickchange_old', event_data[:new_nick])
+  
+  remember(event_data[:new_nick].downcase, event_data[:new_nick],
+             event_data[:user], event_data[:host], '', 'nickchange_new', 
+             event_data[:nick])
+end
+
+@ponder.on :kick do |event_data|
+  remember(event_data[:nick].downcase, event_data[:nick], event_data[:user],
+             event_data[:host], event_data[:channel], 'kicker',
+              "#{event_data[:victim]} #{event_data[:reason]}")
+  
+  remember(event_data[:victim].downcase, event_data[:victim],
+             '', '', event_data[:channel], 'victim', 
+             "#{event_data[:nick]} #{event_data[:reason]}")
+end
+
+def last_seen(nick, event_data)
+  data = @last_seen.hgetall nick
+  
+  case data['action']
+  when 'channel'
+    "#{data['nick']} wrote something in #{data['channel']} at #{Time.at(data['updated_at'].to_i).strftime(FORMAT)}."
+  when 'join'
+    "#{data['nick']} joined #{data['channel']} at #{Time.at(data['updated_at'].to_i).strftime(FORMAT)}."
+  when 'part'
+    "#{data['nick']} left #{data['channel']} at #{Time.at(data['updated_at'].to_i).strftime(FORMAT)} (#{data['action_content']})."
+  when 'quit'
+    "#{data['nick']} quit at #{Time.at(data['updated_at'].to_i).strftime(FORMAT)} (#{data['action_content']})."
+  when 'nickchange_old'
+    "#{data['nick']} renamed to #{data['action_content']}} at #{Time.at(data['updated_at'].to_i).strftime(FORMAT)}."
+  when 'nickchange_new'
+    "#{data['nick']} renamed to #{data['action_content']} at #{Time.at(data['updated_at'].to_i).strftime(FORMAT)}."
+  when 'kicker'
+    "#{data['nick']} kicked #{data['action_content'].split(' ')[0]} at #{Time.at(data['updated_at'].to_i).strftime(FORMAT)} from #{data['channel']} (#{data['action_content'].split(' ')[1]})."
+  when 'victim'
+    "#{data['nick']} was kicked by #{data['action_content'].split(' ')[0]} at #{Time.at(data['updated_at'].to_i).strftime(FORMAT)} from #{data['channel']} (#{data['action_content'].split(' ')[1]})."
+  end
+end
+
+@ponder.on :channel, /^!seen \S+$/ do |event_data|
+  nick = event_data[:message].split(' ')[1].downcase
+  
+  # wildcards
+  if nick =~ /\*/
+    users = @last_seen.keys nick.escape_redis
+    results = users.length
+    
+    case results
+    when 0
+      @ponder.message event_data[:channel], 'No such nick found.'
+    when 1
+      @ponder.message last_seen(users[0])
+    when 2..5
+      nicks = []
+      users.each do |user|
+        nicks << @last_seen.hgetall(user)['nick']
+      end
+      nicks = nicks.join(', ')
+      @ponder.message event_data[:channel], "#{results} nicks found (#{nicks})."
+    else
+      @ponder.message event_data[:channel], "Too many results (#{results})."
+    end
+  # single search
+  elsif @last_seen.exists nick
+    msg = last_seen(nick, event_data)
+    if online_nick = @ponder.whois(nick)
+      msg = "#{online_nick[:nick]} is online. (#{msg})"
+    end
+    @ponder.message event_data[:channel], msg
+  elsif online_nick = @ponder.whois(nick)
+    @ponder.message event_data[:channel], "#{online_nick[:nick]} is online."
+  else
+    @ponder.message event_data[:channel], "#{nick} not found."
+  end
+end
+
+@ponder.connect
+