From: ueno Date: Sun, 14 Aug 2005 01:20:22 +0000 (+0000) Subject: New file. X-Git-Tag: channel-coding-branchpoint~101 X-Git-Url: http://git.chise.org/gitweb/?a=commitdiff_plain;h=b8f236a6bccb3b07f52f73ecb3427ade2fa63012;p=elisp%2Friece.git New file. --- diff --git a/doc/HACKING b/doc/HACKING new file mode 100644 index 0000000..e367c61 --- /dev/null +++ b/doc/HACKING @@ -0,0 +1,446 @@ +-*- mode: text -*- + +This document is for Riece developers. The information necessary for +Riece development is explaind (i.e. its development process and the +internals.) + +* Development process + +** Bug report + +You can create a bug report by clicking the "bug" button in a toolbar, +or M-x riece-submit-bug-report. It is necessary to set riece-debug to +t before preparing a bug report. + +** Debug output + +If the riece-debug variable is set to t, Riece begins to collect +debugging information in *Debug* buffer. + +And also, interactions with IRC servers are stored in +" *IRC*" buffers. Note that the buffer names start +with a whitespace character (" "). + +** Joining the development + +To join the development, send us a patch or an add-on. + +** CVS + +Development of Riece uses CVS. Latest developing version is available +at CVS. Please note that the newest development version from CVS may +_not_ be reliable. You can only use it at your own risk. We may +ignore bug reports for that version. + +(1) logging in to anonymous CVS server + + cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login + CVS password: [CR] # NULL string + +(2) checkout modules + + cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout riece + +(3) generate configure script + + autoreconf -f -i -v + +You will need newer version of GNU Automake. + +* Internals + +** Modules + +Riece consists of elisp modules listed below, ordered by the number of +dependencies. + +- riece-globals + This module defines global variables. + +- riece-options + This module defines user options. + +- riece-version + This module defines the version of Riece. + +- riece-coding + This module provides functions which support code conversions. + +- riece-complete + + This module provides functions which support tab completion in a + mini buffer. + +- riece-addon + This module manages add-ons. + +- riece-mode + This module manages modes of riece-channel/riece-user objects. + +- riece-identity + This module defines the riece-identity object type which represents + global names of riece-channel/riece-user objects. + +- riece-channel + This module defines the riece-channel object type. + +- riece-user + This module defines the riece-user object type. + +- riece-misc + This module provides miscellaneous functions. + +- riece-signal + This module manages routing display signals. + +- riece-layout + This module manages window layouts. + +- riece-display + This module manages display events. + +- riece-server + This module manages connections to IRC servers. + +- riece-naming + This module is a so called Mediator pattern which knows relations of + channels and users. + +- riece-message + This module defines the riece-message object type. + +- riece-filter + This module defines the process filter. + +- riece-handle + This module provides handler definitions for IRC messages. These + handlers are called from riece-filter. + +- riece-000 + This module provides handler definitions for numeric replies whose + response codes are in 000 to 100 range. These handlers are called + from riece-filter. + +- riece-200 + This module provides handler definitions for numeric replies whose + response codes are in 200 to 300 range. These handlers are called + from riece-filter. + +- riece-300 + This module provides handler definitions for numeric replies whose + response codes are in 300 to 400 range. These handlers are called + from riece-filter. + +- riece-400 + This module provides handler definitions for numeric replies whose + response codes are in 400 to 500 range. These handlers are called + from riece-filter. + +- riece-500 + This module provides handler definitions for numeric replies whose + response codes are in 500 to 600 range. These handlers are called + from riece-filter. + +- riece-commands + This module provides commands. + +- riece-irc + This module sets up process-filter for the IRC protocol. + +- riece + This module is the entry point of M-x riece. + +** Namespace management + +Riece is capable to connect to several IRC servers. + +Riece has separate namespace (obarray) for each connection. These +namespaces can be accessed as buffer local variables of process +buffer. + +*** Obtaining server buffer + +To access to the buffer local variables of process buffer, it is +needed to distinguish process object of each connection by its name. + +It can be known by: + +(1) checking the value of riece-overrinding-server-name, + +(2) checking the value of riece-server-name, + (If the variable riece-server-name is local to the current buffer, + you are already in the process buffer.) + +(3) or parsing riece-identity objects + +Once you get the name of the IRC server, you can get the process +object by passing the name to the function riece-server-process. + +*** riece-identity objects + +A riece-identity object represents a name of a channel/user. It is +used to distinguish a channel/user among several servers. + +A riece-identity object is actually a vector, which consists of two +elements listed below. + +- prefix + A channel/user name local to an IRC server. + +- server + The name of the IRC server. + +Methods to manipulate riece-identity object are listed below. + +- riece-make-identity prefix &optional server + Create a new riece-identity object. If the server argument is + omitted, it sets the server part to the value returned by the + riece-find-server-name function. + +- riece-identity-prefix identity + Return the prefix element from the given riece-identity object. + +- riece-identity-server identity + Return the server element from the given riece-identity object. + +- riece-identity-equal ident1 ident2 + Return t, if two riece-identity objects are equal. + +- riece-identity-equal-no-server ident1 ident2 + Return t, if two riece-identity objects are equal. This function + only consider a prefix part of a riece-identity object. + +- riece-identity-member elt list + Return non-nil if a riece-identity object is an element of a list. + +*** Channels and users + +A riece-channel object provides an abstraction of a channel. +Likewise, a riece-user object provides an abstraction of a user. + +**** riece-channel objects + +A riece-channel object has many information about a channel. A +riece-channel object is actually a vector whose seven elements are listed +below. + +- users + A list of nicknames which are of users in this channel. + +- operators + A list of nicknames which are of channel operators in this channel. + +- speakers + A list of nicknames which are of users who have the right to speak + in this channel. + +- modes + An alist which represents modes of this channel. + +- banned + A list of patterns set by MODE +b. + +- invited + A list of patterns set by MODE +I. + +- uninvited + A list of patterns set by MODE +e. + +**** riece-user objects + +A riece-user object has many information about a user. A riece-user +object is actually a vector whose four elements are listed below. + +- channels + A list of channel names this user is participating. + +- user-at-host + Connection information of this user, set in "@" format. + +- modes + An alist which represents modes of this user. + +- away + A flag represent whether this user is AWAY. + +**** The Mediator pattern + +The riece-naming module is used to manage relationships between +channels and users. It utilizes the Mediator design pattern. + +Using the riece-naming module allows to safely access to the namespace +rather than directly connects riece-channel/riece-user objects. + +The riece-naming module provides the following functions. + +- riece-naming-assert-join user-name channel-name + Assert that a user is a member of a channel. + +- riece-naming-assert-part user-name channel-name + Assert that a user is no longer a member of a channel. + +- riece-naming-assert-rename old-name new-name + Assert that a user changed his nickname. + +** Signals + +There is a mechanism to connect events and display objects (windows, +buffers, and modeline indicators). This is done by signals. + +When it is needed to redraw, a signal is emitted. The concept of +signals is corresponding to signals in generic window system toolkit +such as Qt or GTK+. + +To emit a signal, use riece-emit-signal. + +- riece-emit-signal signal-name &rest args + Emit a signal named signal-name with args. + +To define a function called when a signal is emitted, use +riece-connect-signal. + +- riece-connect-signal signal-name slot-function &optional + filter-function handback + + Give a signal a slot-function. The slot-function gets two + arguments: the signal object itself and a handback object given as + the fourth argument of riece-connect-signal. + + If the third argument filter-function is specified, the + slot-function is called conditionaly. The filter-function gets the + signal object and returns nil or t. If the return value is nil, the + slot-function is not called. + +To access to a signal object, use the following functions. + +- riece-signal-name signal + Return the name of a signal. + +- riece-signal-args + Return the data of a signal. + +Below is a list of signal names reserved. + +- channel-list-changed + Need update the channel list. + +- user-list-changed + Need update the user list. + (This signal gets a riece-identity object as an argument which + represents the channel.) + +- channel-switched + A user selected another channel. + +- user-joined-channel + A user joined a channel. + (This signal gets two riece-identity objects as arguments + corresponding to the user and the channel respectively.) + +- user-left-channel + A user left a channel. + (This signal gets two riece-identity objects as arguments + corresponding to the user and the channel respectively.) + +- user-renamed + A user changed his nickname. + (This signal gets two riece-identity objects as arguments + corresponding to the old and the new nickname respectively.) + +- user-away-changed + A user changed his AWAY status. + (This signal gets a riece-identity object as an argument which + represents the user.) + +- user-operator-changed + A user changed his IRC operator status. + (This signal gets a riece-identity object as an argument which + represents the user.) + +- channel-topic-changed + A topic of a channel changed. + (This signal gets a riece-identity object as an argument which + represents the channel.) + +- channel-modes-changed + Modes of a channel changed. + (This signal gets a riece-identity object as an argument which + represents the channel.) + +- channel-operators-changed + A list of operators in a channel changed. + (This signal gets a riece-identity object as an argument which + represents the channel.) + +- channel-speakers-changed + A list of users who have the right to speak in a channel changed. + (This signal gets a riece-identity object as an argument which + represents the channel.) + +- buffer-freeze-changed + A buffer is frozen or unfrozen. + (This signal gets a buffer as an argument.) + +** Writing add-ons + +Elisp modules that satisfy add-on spec should provide the following +functions. + +- -requires + Return a list of names of other add-ons this add-on depends. (optional) + +- -insinuate + Called on initialization of this module. + +It is recommended to set short explanation of the add-on to +-description variable which is displayed on add-on +listing shown up by C-c ^ (M-x riece-command-list-addons). + +Add-ons that support enabling/disabling set the current status to +-enabled variable. If this variable is nil, the add-on +is regarded as currently disabled. In addition, the add-on must +provide the following two functions. + +- -enable + Called to enable this add-on. + +- -disable + Called to disable this add-on. + +Riece does the following process when startup. + +(1) Load add-ons listed in the riece-addons variable. + +(2) Call -requires on each add-on (if exists) and build a + dependency graph. + +(3) Sort the dependency graph. + +(4) Call -insinuate on each add-on in order of the + dependencies. + +(5) Call -enable on each add-on, iff it supports + enabling/disabling and is not disabled explicitly. + +Add-ons are loaded from directories listed in load-path, or from +~/.riece/addons/. + +** Handler hooks + +There are hooks called "handler hooks " which have special meaning in +Riece. Handler hooks are called before/after processing IRC messages. + +- riece--hook + Called before processing an IRC message. + +- riece-after--hook + Called after processing an IRC message. + +Where is a type of IRC message and consists only lowercase +characters. + +If riece--hook returns non-nil, is not processed. +In this case riece-after--hook is not called. + +Handler hooks gets two arguments corresponding to prefix and +parameters in RFC2812.