Plugin DSL

For plugin developers. See lib/plugin.rb for latest :)

DSL

You define plugins by making a file or directory in the plugins folder. The name of the file or directory is the name of your plugin. The plugin DSL makes heavy use of blocks and closures. Checkout existing plugins for more examples and ideas.

Methods

The following methods are available to your plugin:

• command([name=plugin.name],options={},&block)

  Starts a new command block. If you don't give a name, it defaults to the plugin name.

• resource([name=plugin.name],[options={}],[&block])

  shortcut for setting up a command with default actions

• action([name],[options={}],&callback)

  create a new action for the current command (must be called within a command block). See Command DSL for more info.

• timer(seconds, &callback)

• _setup a timer. TODO: callback block has what params?

• send(options={})

  Send a message. Optionas are :to,:from,:html|:txt

• on(event_name, &callback)

  subscribe to an event

• publish(event_name, args...)

  publish an event

• config(name,options,&block)

  Specify a configuration option for your plugin. Options are :description and :default. The optional block param takes 3 args, |value,configured_value,default_value| and it is run whenever the config option is accessed. The result of the block is the value of the config option.

• helper(name,&block)

  Creates a helper method on the plugin object that will be in scope for any of the plugin's blocks. It checks for namespace conflicts (as it will override any plugin function) and warns if it finds one.

Objects

The following objects are in scope for you to reference in your plugin:

• self

  the plugin instance

• plugin

  deprecated

• bot

  the bot instance

• config

  access the config object. any properties you reference must have been setup with a config() DSL call from above, or an error will be raised.

Command DSL

Only valid within command blocks.

• description(str)

  set the description for this command

• aliases(alias1, alias2, ...)

  set one or more aliases for this command

• action([name],[options],&callback)

  create an action. If no name, its a default action. Options are :required, :optional, :html, :is_public, :description. Callback block is called when the command/action regex matches the result of which are sent

TODO

• check action callback arity, and don't pass the msg unless arty is 1 greater than action arty
• better handle conflict on helpers (better scoping somehow?)