--- !ruby/object:RI::MethodDescription 
aliases: []

block_params: 
comment: 
- !ruby/object:SM::Flow::LIST 
  contents: 
  - !ruby/struct:SM::Flow::LI 
    label: "_botmodule_:"
    body: the BotModule which will handle this map
  - !ruby/struct:SM::Flow::LI 
    label: "_template_:"
    body: a String describing the messages to be matched
  - !ruby/struct:SM::Flow::LI 
    label: "_options_:"
    body: a Hash holding variouns options
  type: :NOTE
- !ruby/struct:SM::Flow::P 
  body: "This method is used to register a new MessageTemplate that will map any BasicUserMessage matching the given <em>template</em> to a corresponding action. A simple example:"
- !ruby/struct:SM::Flow::VERB 
  body: "  plugin.map 'myplugin :parameter'\n"
- !ruby/struct:SM::Flow::P 
  body: (other examples follow).
- !ruby/struct:SM::Flow::P 
  body: By default, the action to which the messages are mapped is a method named like the first word of the template. The
- !ruby/struct:SM::Flow::VERB 
  body: "  :action =&gt; 'method_name'\n"
- !ruby/struct:SM::Flow::P 
  body: "option can be used to override this default behaviour. Example:"
- !ruby/struct:SM::Flow::VERB 
  body: "  plugin.map 'myplugin :parameter', :action =&gt; 'mymethod'\n"
- !ruby/struct:SM::Flow::P 
  body: By default whether a handler is fired depends on an auth check. In rbot versions up to 0.9.10, the first component of the string was used for the auth check, unless overridden via the :auth =&gt; 'auth_name' option. Since version 0.9.11, a new auth method has been implemented. TODO document.
- !ruby/struct:SM::Flow::P 
  body: "Static parameters (not prefixed with ':' or '*') must match the respective component of the message exactly. Example:"
- !ruby/struct:SM::Flow::VERB 
  body: "  plugin.map 'myplugin :foo is :bar'\n"
- !ruby/struct:SM::Flow::P 
  body: will only match messages of the form &quot;myplugin something is somethingelse&quot;
- !ruby/struct:SM::Flow::P 
  body: "Dynamic parameters can be specified by a colon ':' to match a single component (whitespace separated), or a * to suck up all following parameters into an array. Example:"
- !ruby/struct:SM::Flow::VERB 
  body: "  plugin.map 'myplugin :parameter1 *rest'\n"
- !ruby/struct:SM::Flow::P 
  body: "You can provide defaults for dynamic components using the :defaults parameter. If a component has a default, then it is optional. e.g:"
- !ruby/struct:SM::Flow::VERB 
  body: "  plugin.map 'myplugin :foo :bar', :defaults =&gt; {:bar =&gt; 'qux'}\n"
- !ruby/struct:SM::Flow::P 
  body: would match 'myplugin param param2' and also 'myplugin param'. In the latter case, :bar would be provided from the default.
- !ruby/struct:SM::Flow::P 
  body: Static and dynamic parameters can also be made optional by wrapping them in square brackets []. For example
- !ruby/struct:SM::Flow::VERB 
  body: "  plugin.map 'myplugin :foo [is] :bar'\n"
- !ruby/struct:SM::Flow::P 
  body: will match both 'myplugin something is somethingelse' and 'myplugin something somethingelse'.
- !ruby/struct:SM::Flow::P 
  body: "Components can be validated before being allowed to match, for example if you need a component to be a number:"
- !ruby/struct:SM::Flow::VERB 
  body: "  plugin.map 'myplugin :param', :requirements =&gt; {:param =&gt; /^\\d+$/}\n"
- !ruby/struct:SM::Flow::P 
  body: will only match strings of the form 'myplugin 1234' or some other number.
- !ruby/struct:SM::Flow::P 
  body: Templates can be set not to match public or private messages using the :public or :private boolean options.
- !ruby/struct:SM::Flow::P 
  body: "Summary of recognized options:"
- !ruby/object:SM::Flow::LIST 
  contents: 
  - !ruby/struct:SM::Flow::LI 
    label: "action:"
    body: method to call when the template is matched
  - !ruby/struct:SM::Flow::LI 
    label: "auth_path:"
    body: TODO document
  - !ruby/struct:SM::Flow::LI 
    label: "requirements:"
    body: a Hash whose keys are names of dynamic parameters and whose values are regular expressions that the parameters must match
  - !ruby/struct:SM::Flow::LI 
    label: "defaults:"
    body: a Hash whose keys are names of dynamic parameters and whose values are the values to be assigned to those parameters when they are missing from the message. Any dynamic parameter appearing in the :defaults Hash is therefore optional
  - !ruby/struct:SM::Flow::LI 
    label: "public:"
    body: a boolean (defaults to true) that determines whether the template should match public (in channel) messages.
  - !ruby/struct:SM::Flow::LI 
    label: "private:"
    body: a boolean (defaults to true) that determines whether the template should match private (not in channel) messages.
  - !ruby/struct:SM::Flow::LI 
    label: "threaded:"
    body: a boolean (defaults to false) that determines whether the action should be called in a separate thread.
  type: :NOTE
- !ruby/struct:SM::Flow::P 
  body: "Further examples:"
- !ruby/struct:SM::Flow::VERB 
  body: "  # match 'karmastats' and call my stats() method\n  plugin.map 'karmastats', :action =&gt; 'stats'\n  # match 'karma' with an optional 'key' and call my karma() method\n  plugin.map 'karma :key', :defaults =&gt; {:key =&gt; false}\n  # match 'karma for something' and call my karma() method\n  plugin.map 'karma for :key'\n\n  # two matches, one for public messages in a channel, one for\n  # private messages which therefore require a channel argument\n  plugin.map 'urls search :channel :limit :string',\n            :action =&gt; 'search',\n            :defaults =&gt; {:limit =&gt; 4},\n            :requirements =&gt; {:limit =&gt; /^\\d+$/},\n            :public =&gt; false\n  plugin.map 'urls search :limit :string',\n            :action =&gt; 'search',\n            :defaults =&gt; {:limit =&gt; 4},\n            :requirements =&gt; {:limit =&gt; /^\\d+$/},\n            :private =&gt; false\n"
full_name: Irc::Bot::MessageMapper#map
is_singleton: false
name: map
params: " map(botmodule, template, options)\n"
visibility: public
