From 0af94ef1798cf6f1cadb7c69dd2561d88cbecc7b Mon Sep 17 00:00:00 2001 From: James Vega Date: Fri, 7 Jul 2006 11:52:35 +0000 Subject: [PATCH] Removing docs/INTERFACES since jemfinch doesn't want to update it and it's nearly useless in its current state. --- docs/INTERFACES | 271 ------------------------------------------------ 1 file changed, 271 deletions(-) delete mode 100644 docs/INTERFACES diff --git a/docs/INTERFACES b/docs/INTERFACES deleted file mode 100644 index 791163351..000000000 --- a/docs/INTERFACES +++ /dev/null @@ -1,271 +0,0 @@ -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).