+
+ # 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
+ #
+ def map(botmodule, *args)
+ @templates << MessageTemplate.new(botmodule, *args)