Extensions
==========
Introduction
------------

participle extensions are an easy way to add grouped, dynamically loadable commands to the bot. Syntax is simple:

    class ClassName < Participle::Extension
      match :testcommand, "command", :usage => "A test command for the bot."

      def testcommand msg, params
        msg.reply "Tested a new command."
      end
    end

To load an extension, stick the extension class file into /ext, and add the class name to the "extensions" directive in the bot configuration in main.rb. The class name, following Rails conventions, should be in camelCase and the file name itself should be under\_scored.

The <code>match</code> Command
------------------------------

<code>match</code> is the basic extension class method: the way to map a command to a subroutine and define its other characteristics. The syntax is:

    match :function_name, "command string", {other arguments}

"other arguments" in this case will be a symbol-keyed hash of extra command characteristics. Valid keys:

* <code>:usage [string]</code>: The usage instructions. Default is nil.
* <code>:admin [boolean]</code>: Whether to restrict this function to the bot's admin or not. Default is false.
* <code>:event [symbol, optional]</code>: Event to fire this command on. Default is :message, options are :join and :botjoin.
* <code>:trigger [boolean]</code>: Whether a trigger is necessary to fire this command. Default is true.

Command syntax
--------------
Command arguments can be in string or Regexp format. In a Regexp, the capture groups are passed to the matching function. In a string, the syntax is somewhat more advanced. Any normal text can be used; words that are prefixed with semicolons (:), however, will be treated as command arguments. They match greedily (as much of the string as they can). Optional arguments are instead prefixed with a semicolon and a question mark (:?). Example:

    note :cmd :id :?option

Resulting in:

    "note add 3" #=> {:cmd => "add", :id => "3"}
    "note remove" #=> does not match
    "note add 5 verbose" #=> {:cmd => "add", :id => "5", :option => "verbose"}
    "note add 7 a bunch of extra options" #=> {:cmd => "add", :id => "7", :option => "a bunch of extra options"}

The matching parameters are then passed to the command's associated function, along with a Message object.

The Message Object
------------------
Participle::Message is a neat little object that allows easy access to dAmn chat commands. Instance methods involve Message#reply, which merely prints something out in the current room. Message#user is an object which contains basic data about the user who said the line. See lib/message.rb for more information.

The <code>load</code> Command
-----------------------------
Participle::Extension.load is just a wrapper around <code>gem</code>, <code>require</code>, and <code>Kernel.load</code> to make errors more manageable and user-friendly. <code>load</code> can be used to load gems or files from /ext/classes.

    load :rsa # Loads RSA gem
    load :hello # Loads hello.rb from /ext/classes/hello