dr.botzo/Module.py

# Module - dr.botzo modular functionality base class
# Copyright (C) 2010  Brian S. Stephan
#
# 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 inspect
import re
import sys

from irclib import irclib

# Base class used for creating classes that have real functionality.

class Module(object):

    # Constructor for a feature module. Inheritors should not do anything special
    # here, instead they should implement register_handlers and do, or else this will
    # be a very uneventful affair.
    #
    # Classes that are interested in allowing an indirect call to their do routine
    # should add themselves to modlist inside their __init__. This will allow other
    # modules to call do and see if anything can handle text they may have seen (such
    # as in recursive commands).

    def __init__(self, config, server, modlist):
        self.config = config
        self.server = server
        self.modlist = modlist
        self.register_handlers(server)

        # add self to the object list
        modlist.append(self)

        # print what was loaded, for debugging
        print("loaded " + self.__class__.__name__)

    # This is called by __init__ and sets up server.add_global_handlers. Classes
    # inheriting from Module should implement this and set up the appropriate handlers,
    # e.g.:
    #
    # server.add_global_handler('privmsg', self.on_privmsg)
    #
    # Module.on_pubmsg and Module.on_privmsg are defined so far, the rest, you're on your
    # own.

    def register_handlers(self, server):
        print "looks like someone forgot to implement register_handlers!"

    # This is called by reload, to remove the soon-to-be old object from the server
    # global handlers (or whatever has been added via register_handlers). Classes
    # inheriting from Module should implement this, e.g.:
    #
    # server.remove_global_handler('privmsg', self.on_privmsg)

    def unregister_handlers(self):
        print "looks like someone forgot to implement unregister_handlers!"

    # Does some variable setup and initial sanity checking before calling Module.do,
    # which should be implemented by subclasses and what can be ultimately responsible
    # for the work. Of course, you are free to reimplement on_pubmsg on your own too.

    def on_pubmsg(self, connection, event):
        nick = irclib.nm_to_n(event.source())
        userhost = irclib.nm_to_uh(event.source())
        replypath = event.target()
        what = event.arguments()[0]

        admin_unlocked = False

        try:
            if userhost == self.config.get('admin', 'userhost'):
                admin_unlocked = True
        except NoOptionError: pass

        # only do commands if the bot has been addressed directly
        addressed_pattern = '^' + connection.get_nickname() + '[:,]?\s+'
        addressed_re = re.compile(addressed_pattern)

        if not addressed_re.match(what):
            return
        else:
            what = addressed_re.sub('', what)

        if replypath is not None:
            what = self.try_recursion(connection, event, nick, userhost, replypath, what, admin_unlocked)

        # try reloading
        self.reload(connection, event, nick, userhost, replypath, what, admin_unlocked)

        self.do(connection, event, nick, userhost, replypath, what, admin_unlocked)

    # Does some variable setup and initial sanity checking before calling Module.do,
    # which should be implemented by subclasses and what can be ultimately responsible
    # for the work. Of course, you are free to reimplement on_privmsg on your own too.

    def on_privmsg(self, connection, event):
        nick = irclib.nm_to_n(event.source())
        userhost = irclib.nm_to_uh(event.source())
        replypath = nick
        what = event.arguments()[0]

        admin_unlocked = False

        try:
            if userhost == self.config.get('admin', 'userhost'):
                admin_unlocked = True
        except NoOptionError: pass

        if replypath is not None:
            what = self.try_recursion(connection, event, nick, userhost, replypath, what, admin_unlocked)

        self.do(connection, event, nick, userhost, replypath, what, admin_unlocked)

    # If the command given was to reload, reload this module.

    def reload(self, connection, event, nick, userhost, replypath, what, admin_unlocked):
        whats = what.split(' ')
        if whats[0] == 'reload' and admin_unlocked:
            # re-read and re-compile module from source on disk
            reload(sys.modules[self.__module__])

            # find the class declaration for the current module
            for name, obj in inspect.getmembers(sys.modules[self.__module__]):
                if inspect.isclass(obj) and str(obj).find(self.__module__) > 0:
                    # remove existing object from in-memory stuff
                    self.modlist.remove(self)
                    self.unregister_handlers()

                    # create new object, like how we did initially
                    obj(self.config, self.server, self.modlist)

    # Utility method to do the proper type of reply (either to IRC, or as a return
    # to caller) depending on the target. Pretty simple, and included in the base
    # class for convenience. It should be the last step for callers:
    #
    # return self.reply(connection, replypath, 'hello')

    def reply(self, connection, replypath, replystr):
        if replypath is None:
            return replystr
        else:
            connection.privmsg(replypath, replystr)

    # Upon seeing a line intended for this module, see if there are subcommands
    # that we should do what is basically a text replacement on. The intent is to
    # allow things like the following:
    #
    # command arg1 [anothercommand arg1 arg2]
    #
    # where the output of anothercommand is command's arg2..n. It's mostly for
    # amusement purposes, but maybe there are legitimate uses. This is intended to
    # be attempted after you've determined the line should be handled by your module.

    def try_recursion(self, connection, event, nick, userhost, replypath, what, admin_unlocked):
        start_idx = what.find('[')
        subcmd = what[start_idx+1:]
        end_idx = subcmd.rfind(']')
        subcmd = subcmd[:end_idx]

        attempt = what

        if start_idx == -1 or end_idx == -1:
            # no nested commands at all if replypath is a real value, so don't do a damn thing
            if replypath is not None:
                return attempt
            # no more replacements found, see if what we had is workable
            else:
                for module in self.modlist:
                    ret = module.do(connection, event, nick, userhost, None, attempt, admin_unlocked)
                    if ret is not None:
                        return ret

                # if we got here, it's not workable. just return what we got
                return attempt
        else:
            # we have a subcmd, see if there's another one nested
            ret = self.try_recursion(connection, event, nick, userhost, None, subcmd, admin_unlocked)
            if ret is not None:
                blarg = attempt.replace('['+subcmd+']', ret)
                if replypath is not None:
                    return blarg
                else:
                    return self.try_recursion(connection, event, nick, userhost, None, blarg, admin_unlocked)
            else:
                return attempt

    # Implement this method in your subclass to have a fairly-automatic hook into
    # IRC functionality. This is called by the default on_pubmsg and on_privmsg

    def do(self, connection, event, nick, userhost, replypath, what, admin_unlocked):
        print "looks like someone forgot to implement do!"

# vi:tabstop=4:expandtab:autoindent
# kate: indent-mode python;indent-width 4;replace-tabs on;