"""
Help - handle !help commands by interrogating modules for help text
Copyright (C) 2011  Mike Bloy <mike@bloy.org>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
"""

import re

from Module import Module

__author__ = "Mike Bloy <mike@bloy.org>"
__date__ = "2011-01-08"

class Help(Module):

    def __init__(self, irc, config):
        """
        Upon creation, determine the save file location
        """

        Module.__init__(self, irc, config)

        self.helpre = re.compile('^!help(\s+(\S+)(\s+(.+))?)?\s*$')

    def do(self, connection, event, nick, userhost, what, admin_unlocked):
        """look for !help and subcommands,
        and dispatch for further processing"""

        match = self.helpre.search(what)
        if match:
            (module, key) = match.group(2,4)
            if (module == None):
                return self.irc.reply(event, self.handle_help_descriptions())
            elif (key == None):
                return self.irc.reply(event, self.handle_help_module(module))
            else:
                return self.irc.reply(event, self.handle_help_detail(module, key))

    def handle_help_descriptions(self):
        """print the general help"""
        message = "General Help:\n"
        for module in self.irc.modlist:
            description = module.help_description()
            if description:
                message += "  %s - %s\n" % (module.__class__.__name__,
                                           description)
        return message

    def handle_help_module(self, modname):
        """handle the module level help processing"""
        module = self.find_module(modname)
        if module:
            helptext = module.help_summary()
            if helptext:
                return "%s - %s" % (modname, helptext)
            else:
                return "no help available for module %s" % (modname)
        else:
            return "no module named '%s' is loaded" % (modname)

    def handle_help_detail(self, modname, key):
        """handle the help detail message"""
        module = self.find_module(modname)
        if module:
            helptext = module.help_detail(key)
            if helptext:
                return "%s (%s) - %s" % (modname, key, helptext)
            else:
                return "no help available for module '%s', command '%s'" % (modname, key)
        else:
            return "no module named '%s' is loaded" % (modname)

        return "asked for help on module %s detail %s" % (modname, key)

    def find_module(self, modname):
        """find a module in the server's list of loaded modules"""
        for module in self.irc.modlist:
            if modname == module.__class__.__name__:
                return module
        return None

    def help_description(self):
        """Return a quick list of commands or other summary, should be
        less than two lines. If you want the module hidden from "!help",
        return None here"""
        return "Display module and command help"

    def help_summary(self):
        """Return a command summary or longer description of this module.
        If this returns None, the summary will be
        "no help available for module foo"
        """
        return """!help [module [detail]]
type '!help Help module' or '!help Help detail' for more information"""

    def help_detail(self, command):
        """Return detailed help for the given command. Return None if there
        is no suitable help available"""
        if command == 'module':
            return """get a summary of a module's commands or function"""
        elif command == 'detail':
            return """get information on a specific module-defined detail"""
        else:
            return None

if __name__ == "__main__":
    print "Hello World"

# vi:tabstop=4:expandtab:autoindent