Limnoria/docs/INTERFACES

These are the interfaces for some of the objects you'll deal with if
you code for Supybot.

ircmsgs.IrcMsg:
    This is the object that represents an IRC message.  It has
    several methods and attributes.  The most important thing
    about this class, however, is that it *is* hashable, and thus
    *cannot* be modified.  Do not change any attributes; any code
    that modifies an IRC message is *broken* and should not
    exist.

    Interesting Methods:
            __init__: One of the more complex initializers in 
            a class.  It can be used in three different ways:

            1) It can be given a string, as one received from
                       the server, which it will then parse into its
                       separate components and instantiate the class
                       with those components as attributes.

            2) It can be given a command, some (optional)
                       arguments, and a (optional) prefix, and will
                       instantiate the class with those components as
                       attributes.

            3) It can be given, in addition to any of the
                       above arguments, a 'msg' keyword argument that
                       will use the attributes of msg as defaults.
                       This exists to make it easier to copy
                       messages, since the class is immutable.

            __str__: This returns the message in a string form
            suitable for sending to a server.

            __repr__: This returns the message in a form
            suitable for eval(), assuming the name "IrcMsg" is
            in your namespace and is bound to this class.

    Interesting Attributes:
            This is the meat of this class.  These are
            generally what you'll be looking at with IrcMsgs.

            command: This is the command of the IrcMsg --
            PRIVMSG, NOTICE, WHOIS, etc.

            args: This is a tuple of the arguments to the
            IrcMsg.  Some messages have arguments, some don't,
            depending on what command they are.  You are, of
            course, always assured that args exists and is a
            tuple, though it might be empty.

            prefix: This is the hostmask of the person/server
            the message is from.  In general, you won't be
            setting this on your outgoing messages, but
            incoming messages will always have one.  This is
            the whole hostmask; if the message was received
            from a server, it'll be the server's hostmask; if
            the message was received from a user, it'll be the
            whole user hostmask.  In that case, however, it's
            also parsed out into the nick/user/host
            attributes, which are probably more useful to
            check for many purposes.

            nick: If the message was sent by a user, this will
            be the nick of the user.  If it was sent by a
            server, this will be the server's name (something
            like calvino.freenode.net or similar).

            user: If the message was sent by a user, this will
            be the user string of the user -- what they put
            into their IRC client for their "full name."  If
            it was sent by a server, it'll be the server's
            name, again.

            host: If the message was sent by a user, this will
            be the host portion of their hostmask.  If it was
            sent by a server, it'll be the server's name (yet
            again :))
         
                       
irclib.Irc:
    This is the object to handle everything about IRC except the
    actual connection to the server itself.  (*NOTE* that the
    object actually received by commands in subclasses of
    callbacks.Privmsg is an IrcObjectProxy, which is described
    later.  It augments the following interface with several
    methods of its own to help plugin authors.)

    Interesting Methods:
            The two following messages (queueMsg and
            sendMsg) are the methods by far most commonly
            called by plugin authors.  They're generally
            the only methods you need to pay attention to
            if you're writing plugins.
            
            queueMsg: Queues a message for sending to the
            server.  The queue is generally FIFO, but it
            does prioritize messages based on their command.

            sendMsg: Queues a message for sending to the
            server prior to any messages in the normal
            queue.  This is exactly a FIFO queue, no
            reordering is done at all.

            The following two methods are the most important
            for people writing new IrcDrivers.  Otherwise,
            you really don't need to pay attention to them.

            feedMsg: Feeds the Irc object a message for it
            handle appropriately, as well as passing it on
            to callbacks.

            takeMsg: If the Irc object has a message it's
            ready to send to the server, this will return
            it.  Otherwise, it will return None.

            The next several methods are of far more marginal
            utility.  But someone may need them, so they're
            documented here.

            addCallback: Takes a callback to add to the list
            of callbacks in the Irc object.  See the
            interface for IrcCallback for more information.

            getCallback: Gets a callback by name, if it is
            in the Irc object's list of callbacks.  If it
            it isn't, returns None.

            removeCallback: Removes a callback by name.
            Returns a list of the callbacks removed (since
            it is technically possible to have multiple
            callbacks with the same name.  This list may
            be empty.

            __init__: Requires a nick.  Optional arguments
            include user and ident, which default to the
            nick given, password, which defaults to the empty
            password, and callbacks, a list of callbacks
            (which defaults to nothing, an empty list).

            reset: Resets the Irc object to its original
            state, as well as sends a reset() to every
            callbacks.

            die: Kills the IRC object and all its callbacks.

    Interesting attributes:
            nick: The current nick of the bot.

            prefix: The current prefix of the bot.

            server: The current server the bot is connected to.
                    Usually consists of a (host, port) pair.

            afterConnect: False until the bot has received a
                          command sent after the connection is finished --
                          376, 377, or 422.

            state: An IrcState object for this particular
                    connection.  See the interface for the IrcState
                    object for more information.


irclib.IrcCallback:
    Interesting Methods:
            name: Returns the name of the callback.  The
            default implementation simply returns the name
            of the class.

            __call__: Called by the Irc object with itself
            and the message whenever a message is fed to
            the Irc object.  Nothing is done with the return
            value.

            inFilter: Called by the Irc object with itself
            and the message whenever a message is fed to
            the Irc object.  The return value should be an
            IrcMsg object to be passed to the next callback
            in the Irc's list of callbacks.  If None is
            returned, all processing stops.  This gives
            callbacks an oppurtunity to "filter" incoming
            messages before general callbacks are given
            them.

            outFilter: Basically equivalent to inFilter,
            except instead of being called on messages
            as they enter the Irc object, it's called on
            messages as they leave the Irc object.

            die: Called when the parent Irc is told to
            die.  This gives callbacks an oppurtunity to
            close open files, network connections, or
            databases before they're deleted.

            reset: Called when the parent Irc is told to
            reset (which is generally when reconnecting
            to the server).  Most callbacks don't need
            to define this.

    Interesting attributes:
            priority: Determines the priority of the
            callback in the Irc object's list of
            callbacks.  Defaults to 99; the valid range
            includes 0 through sys.maxint-1 (don't use
            sys.maxint itself, that's reserved for the
            Misc plugin).  The lower the number, the
            higher the priority.  High priority
            callbacks are called earlier in the
            inFilter cycle, earlier in the __call__
            cycle, and later in the outFilter cycle --
            basically, they're given the first chances
            on the way in and the last chances on the
            way out.


callbacks.IrcObjectProxy:
    IrcObjectProxy is a proxy for an irclib.Irc instance that
    serves to provide a much fuller interface for handling
    replies and errors as well as to handle the nesting of
    commands.  This is what you'll be dealing with almost all the
    time when writing commands; when writing doCommand methods
    (the kind you read about in the interface description of
    irclib.IrcCallback) you'll be dealing with plain old
    irclib.Irc objects.

    Interesting methods:
            reply: Called to reply to the current message
            with a string that is to be the reply.

            replySuccess, replyError: These reply with the
            configured responses for success and generic
            error, respectively.  If an additional argument
            is given, it's (intelligently) appended to the
            generic message to be more specific.

            error: Called to send an error reply to the
            current message; not only does the response
            indicate an error, but commands that error out
            break the nested-command chain, which is
            generally useful for not confusing the user :)

            errorNoCapability: Like error, except it accepts
            the capability that's missing and integrates it
            into the configured error message for such
            things.  Also accepts an additional string for a
            more descriptive message, if that's what you
            want.

            errorPossibleBug, errorNotRegistered,
            errorNoUser, errorRequiresPrivacy: These methods
            reply with the appropriate configured error
            message for the conditions in their names; they
            all take an additional arguments to be more
            specific about the conditions they indicate, but
            this argument is very rarely necessary.

            getRealIrc: Returns the actual Irc object being
            proxied for.