diff --git a/docs/INTERFACES b/docs/INTERFACES new file mode 100644 index 000000000..791163351 --- /dev/null +++ b/docs/INTERFACES @@ -0,0 +1,271 @@ +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. + + network: The current network name the bot is connected to. + + 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. + + replies: Sends a collection of messages to a given + target, much like reply; except in this case, the user + can configure whether the messages will be sent + one-by-one or combined into a single message. Thus, the + method accepts a "prefixer" argument, which prefixes the + messages with a given string (or according to a given + function), a "joiner" string (or function) used to join + the messages into a single message if necessary, and an + onlyPrefixFirst argument which determines whether only + the first message will be prefixed when the messages are + sent separately (it defaults to False).