Class Irc::MessageMapper
In: lib/rbot/messagemapper.rb
Parent: Object

MessageMapper is a class designed to reduce the amount of regexps and string parsing plugins and bot modules need to do, in order to process and respond to messages.

You add templates to the MessageMapper which are examined by the handle method when handling a message. The templates tell the mapper which method in its parent class (your class) to invoke for that message. The string is split, optionally defaulted and validated before being passed to the matched method.

A template such as "foo :option :otheroption" will match the string "foo bar baz" and, by default, result in method foo being called, if present, in the parent class. It will receive two parameters, the Message (derived from BasicUserMessage) and a Hash containing 

  {:option => "bar", :otheroption => "baz"}

See the map method for more details.

Methods

each   handle   last   map   new  

Attributes

fallback  [W]  used to set the method name used as a fallback for unmatched messages. The default fallback is a method called "usage".

Public Class methods

new(parent)
parent:parent class which will receive mapped messages

create a new MessageMapper with parent class parent. This class will receive messages from the mapper via the handle() method.

Public Instance methods

handle(m)
m:derived from BasicUserMessage

examine the message m, comparing it with each map()’d template to find and process a match. Templates are examined in the order they were map()’d - first match wins.

returns true if a match is found including fallbacks, false otherwise.

map(*args)
args:hash format containing arguments for this template

map a template string to an action. example: 

  map 'myplugin :parameter1 :parameter2'

(other examples follow). By default, maps a matched string to an action with the name of the first word in the template. The action is a method which takes a message and a parameter hash for arguments.

The :action => ‘method_name’ option can be used to override this default behaviour. Example: 

  map 'myplugin :parameter1 :parameter2', :action => 'mymethod'

By default whether a handler is fired depends on an auth check. The first component of the string is used for the auth check, unless overridden via the :auth => ‘auth_name’ option.

Static parameters (not prefixed with ’:’ or ’*’) must match the respective component of the message exactly. Example: 

  map 'myplugin :foo is :bar'

will only match messages of the form "myplugin something is somethingelse"

Dynamic parameters can be specified by a colon ’:’ to match a single component (whitespace seperated), or a * to suck up all following parameters into an array. Example: 

  map 'myplugin :parameter1 *rest'

You can provide defaults for dynamic components using the :defaults parameter. If a component has a default, then it is optional. e.g: 

  map 'myplugin :foo :bar', :defaults => {:bar => 'qux'}

would match ‘myplugin param param2’ and also ‘myplugin param’. In the latter case, :bar would be provided from the default.

Components can be validated before being allowed to match, for example if you need a component to be a number: 

  map 'myplugin :param', :requirements => {:param => /^\d+$/}

will only match strings of the form ‘myplugin 1234’ or some other number.

Templates can be set not to match public or private messages using the :public or :private boolean options.

Further examples: 

  # match 'karmastats' and call my stats() method
  map 'karmastats', :action => 'stats'
  # match 'karma' with an optional 'key' and call my karma() method
  map 'karma :key', :defaults => {:key => false}
  # match 'karma for something' and call my karma() method
  map 'karma for :key'

  # two matches, one for public messages in a channel, one for
  # private messages which therefore require a channel argument
  map 'urls search :channel :limit :string', :action => 'search',
            :defaults => {:limit => 4},
            :requirements => {:limit => /^\d+$/},
            :public => false
  plugin.map 'urls search :limit :string', :action => 'search',
            :defaults => {:limit => 4},
            :requirements => {:limit => /^\d+$/},
            :private => false

[Validate]