commands: add a 'help' command (closes #8)

Fetch the docstring of the command function if it exists, and format appropriately.

plugins/commands.py

@@ -17,6 +17,9 @@ def debug(irc, source, args):
 
 @utils.add_cmd
 def status(irc, source, args):
+    """takes no arguments.
+
+    Returns your current PyLink login status."""
     identified = irc.users[source].identified
     if identified:
         utils.msg(irc, source, 'You are identified as %s.' % identified)
@@ -25,11 +28,15 @@ def status(irc, source, args):
 
 @utils.add_cmd
 def identify(irc, source, args):
+    """<username> <password>
+
+    Logs in to PyLink using the configured administrator account."""
     try:
         username, password = args[0], args[1]
     except IndexError:
         utils.msg(irc, source, 'Error: not enough arguments.')
         return
+    # Usernames are case-insensitive, passwords are NOT.
     if username.lower() == conf['login']['user'].lower() and password == conf['login']['password']:
         realuser = conf['login']['user']
         irc.users[source].identified = realuser
@@ -41,7 +48,39 @@ def identify(irc, source, args):
                     irc.name, username, u.nick, u.ident, u.host, u.uid)
 
 def listcommands(irc, source, args):
+    """takes no arguments.
+
+    Returns a list of available commands PyLink has to offer."""
     cmds = list(utils.bot_commands.keys())
     cmds.sort()
     utils.msg(irc, source, 'Available commands include: %s' % ', '.join(cmds))
+    utils.msg(irc, source, 'To see help on a specific command, type \x02help <command>\x02.')
 utils.add_cmd(listcommands, 'list')
+
+@utils.add_cmd
+def help(irc, source, args):
+    """<command>
+
+    Gives help for <command>, if it is available."""
+    try:
+        command = args[0].lower()
+    except IndexError:  # No argument given, just return 'list' output
+        listcommands(irc, source, args)
+        return
+    try:
+        func = utils.bot_commands[command]
+    except KeyError:
+        utils.msg(irc, source, 'Error: no such command %r.' % command)
+        return
+    else:
+        doc = func.__doc__
+        if doc:
+            lines = doc.split('\n')
+            # Bold the first line, which usually just tells you what
+            # arguments the command takes.
+            lines[0] = '\x02%s %s\x02' % (command, lines[0])
+            for line in lines:
+                utils.msg(irc, source, line.strip())
+        else:
+            utils.msg(irc, source, 'Error: Command %r doesn\'t offer any help.' % command)
+            return