Plugins

You define plugins by making a file or directory in the plugins folder (can set multiple plugin directories in the Config). The name of the file or directory is the name of your plugin. The plugin DSL makes heavy use of blocks and closures. Checkout examples below existing plugins directory and the examples below for more ideas. You use the Plugin DSL to specify the what the plugin does, and ruby code to implement the logic.

Commands

A plugin usually implements one or more commands. A command is something the bot does in response to a chat.

Typical pattern:

<command> <action> <arg1>
<command> <action> <arg1> <arg2>
<command> <action> [<arg1>]

Often with a default action:

<command> [<action>]                                  # default no arg action
<command> [<action>] <arg1>                           # default 1 arg (optional or required)
<command> [<action>] <arg1> <arg2>                    # default 2 arg (optional or required)
<command> [<action>] [<arg>]                          # default N arg (optional or required)

Actions

Each command syntax has a corresponding regex and behavior. We call this an action. For this to work, we must sort each action regex by [name>no-name (aka default action), then by higher required arity]. Something like:

/^command\s+action\s+(.*?)\s*$/
/^command\s+action\s*$/
/^command\s+(.*?)\s+(.*?)\s*$/  ; run command.default($1,$2)
/^command\s+(.*?)\s*$/  ; run command.default($1)
/^command\s*$/  ; run command.default() note: lowest arity so must sort last

Examples

Plugin Plugin

This is a fun name :)

syntax:

plugin [list]
plugin [status] <name>
plugin enable <name> 
plugin disable <name> 

code:

command do |cmd|
  description  'manage plugins'

    action :list, :default=>true do |msg|
    end

   action :show, :required=>:plugin, :default=>true do |msg,plugin|
   end

   action :enable, :optional=>:plugin  do |msg,plugin|
   end

   action :disable, :required=>:plugin do |msg,plugin|
   end
end

produces the following regexes:

/^plugin\s+show\s+(.*)$/      # plugin.show($1)
/^plugin\s+show\s+$/          # plugin.show()
/^plugin\s+enable\s+(.*)$/    # plugin.enable($1)
/^plugin\s+enable\s+(.*)$/    # plugin.disable($1)
/^plugin\s+(.*)$/             # default, run plugin.show($1)
/^plugin\s*$/                 # default action, run first noarg plugin action

Hot Plugin

syntax:

hot [trending]
hot [search] <topic>

code:

command :hot do
  description 'Whats hot on twitter'

  action :trending, :default=>true do 
    format(trending())
  end

  action :search, :required=>:topic, :default=>true do |topic|
    format(search(topic))
  end

  helper :format do |tweet|
    # ...
  end

  helper :search do |topic|
    # ...
  end

end

regexes:

/^hot\s+search\s+(.*?)\s*$/       # run hot.search($1)
/^hot\s+trending\s*$/             # run hot.trending()
/^hot\s+(.*?)\s*$/                # run hot.search($1)
/^hot\s*$/                        # run hot.trending()

Lunch Plugin

This plugin is a resource like plugin that manages places to eat lunch at.

resource :description => "Manage lunch resource."

creates the following command syntax:

lunch add <name>      # add new lunch
lunch del <name>      # remove lunch
lunch list            # shows all lunch
lunch [sample]        # shows random from list, default action

which is equivalent to:

command :lunch do
  description "foo"

  action :list do
    # ...
  end

  action :add, :alias=>[:+], :required=>:name do |msg,name|
    # ...
  end

  action :delete, :alias=>[:del,:-] do  |msg,name|
    # ...
  end

  action :sample, :default=>true do
    # ...
  end
end