Split different bot responses out into functions

[jvperrin]

As suggested as part of the feedback for #17, splitting up the different ircbot responses into separate functions would be a good thing to do to refactor how the bot works.

[jvperrin]

This actually might make #1 easier to do as well if each function has its own description of what it does or some details of how to call it. Then all the functions could be aggregated in a help function for the bot.

[matthew-mcallister]

You mean like a docstring?

[chriskuehl]

Here's an API proposal:

• ircbot/ircbot.py contains core bot code:
  • handles received text, dispatches to plugins to answer it
  • at the start, scans the plugin package and registers all the plugin listeners
  • functions for printing text (that properly handles splitting it up, for example)
  • sets up the threads
• ircbot/plugin/ contains plugins, one per file.
  • ircbot/plugin/rackspace_monitoring.py
  • ircbot/plugin/regex.py
  • ircbot/plugin/weather.py
  • ...etc...

Here's an example plugin ircbot/plugin/approve.py:

"""Handle account creation."""

def config(listen):
    listen('^approve (\S+)$', approve_account, help='approve a pending account')
    listen('^list$', list_pending, help='list pending accounts')

def approve_account(bot, match):
    account = match.group(1)
    bot.respond('approved account {}!'.format(account))

def list_pending(bot, match):
    bot.respond('pending accounts: ...')

This API has some benefits:

• Plugins are independent from the main bot code, easy to add new ones
• Each action is easy to test either manually or automatically (it's a pure function, you can pretty much call it without launching a bot if you just pass a mock in as the first argument)
• Easy to expand to timer events by adding more stuff to the config entrypoint
• Easy to automatically generate help

Here's an example of help documentation it could generate:

# Handle account creation
* `create: ^approve (\S+)$` - approve a pending account
* `create: ^list$` - list pending accounts

# View monitoring status
* `create: ^status$` - see current monitoring alarms

# Emoji search
* `create: ^emoji (.+)$` - find matching emojis
* `create: ^remoji (.+)$` - print descriptions of the emojis

The help is probably the most awkward part about this since the regexes look bizarre. Not sure if that's worth fixing (e.g. by adding another param to listen) or not. The help still looks pretty useful to me.

Thoughts?