3 This document is for Riece developers or those who are interested in
4 becoming a developer. The main topic explained here is about
5 development process and the internals.
11 You can create a template of a bug report by clicking the "bug" button
12 in a toolbar, or M-x riece-submit-bug-report. You need to set
13 riece-debug to t when preparing a bug report.
17 If riece-debug is t, "*Debug*" buffer will have debugging information.
18 Also, interactions with IRC servers will be written to "
19 *IRC*<IRC-server-name>" buffers. Note that these buffers have a name
20 starting with a whitespace character (" ").
22 ** Joining the development
24 To join the development, send us a patch or an add-on.
28 The development of Riece uses CVS. The latest development version is
29 available from cvs.m17n.org. The instructions to obtain and build the
30 source from the CVS are below.
34 cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout riece
36 You can specify a tag in front of the module name.
38 (2) generate configure script
42 Note that "autoreconf" is not "autoconf".
48 Riece consists of many elisp modules listed below, ordered by the
49 number of dependencies they have.
52 This module defines global variables.
55 This module defines user options.
58 This module defines the version of Riece.
61 This module provides functions which support character code conversions.
64 This module provides functions which support tab completion feature
68 This module manages add-ons.
71 This module manages modes of riece-channel/riece-user objects.
74 This module defines the riece-identity object type which represents
75 global names of riece-channel/riece-user objects.
78 This module defines the riece-channel object type.
81 This module defines the riece-user object type.
84 This module provides miscellaneous functions.
87 This module defines the riece-signal object type used to manage
91 This module manages window layouts.
94 This module manages display events.
97 This module manages connections to IRC servers.
100 This module is a so called the Mediator design pattern. It knows
101 relationships of riece-channel/riece-user objects.
104 This module defines the riece-message object type.
107 This module only provides the process filter function.
110 This module provides handler functions for IRC messages. These
111 functions are called from riece-filter.
114 This module provides handler functions for numeric replies whose
115 response codes are in 000 to 100 range. These handlers are called
119 This module provides handler functions for numeric replies whose
120 response codes are in 200 to 300 range. These handlers are called
124 This module provides handler functions for numeric replies whose
125 response codes are in 300 to 400 range. These handlers are called
129 This module provides handler functions for numeric replies whose
130 response codes are in 400 to 500 range. These handlers are called
134 This module provides handler functions for numeric replies whose
135 response codes are in 500 to 600 range. These handlers are called
139 This module provides user commands.
142 This module provides the binding for the IRC protocol.
145 This module is the entry point of M-x riece.
147 ** Namespace management
149 Riece is capable to connect to several IRC servers.
151 Riece has separate namespace (obarray) for each connection. These
152 namespaces can be accessed as buffer local variables of process
155 *** Obtaining server buffer
157 To access to the buffer local variables of process buffer, it is
158 needed to distinguish process object of each connection by its name.
162 (1) checking the value of riece-overriding-server-name,
164 (2) checking the value of riece-server-name,
165 (If the variable riece-server-name is local to the current buffer,
166 you are already in the process buffer.)
168 (3) or parsing riece-identity objects
170 Once you get the name of the IRC server, you can get the process
171 object by passing the name to the function riece-server-process.
173 *** riece-identity objects
175 A riece-identity object represents a name of a channel/user. It is
176 used to distinguish a channel/user among several servers.
178 A riece-identity object is actually a vector, which consists of two
179 elements listed below.
182 A channel/user name local to an IRC server.
185 The name of the IRC server.
187 Methods to manipulate riece-identity object are listed below.
189 - riece-make-identity prefix &optional server
190 Create a new riece-identity object. If the server argument is
191 omitted, it sets the server part to the value returned by the
192 riece-find-server-name function.
194 - riece-identity-prefix identity
195 Return the prefix element from the given riece-identity object.
197 - riece-identity-server identity
198 Return the server element from the given riece-identity object.
200 - riece-identity-equal ident1 ident2
201 Return t, if two riece-identity objects are equal.
203 - riece-identity-equal-no-server ident1 ident2
204 Return t, if two riece-identity objects are equal. This function
205 only consider a prefix part of a riece-identity object.
207 - riece-identity-member elt list
208 Return non-nil if a riece-identity object is an element of a list.
210 *** Channels and users
212 A riece-channel object provides an abstraction of a channel.
213 Likewise, a riece-user object provides an abstraction of a user.
215 **** riece-channel objects
217 A riece-channel object has many information about a channel. A
218 riece-channel object is actually a vector whose seven elements are listed
222 A list of nicknames which are of users in this channel.
225 A list of nicknames which are of channel operators in this channel.
228 A list of nicknames which are of users who have the right to speak
232 An alist which represents modes of this channel.
235 A list of patterns set by MODE +b.
238 A list of patterns set by MODE +I.
241 A list of patterns set by MODE +e.
243 **** riece-user objects
245 A riece-user object has many information about a user. A riece-user
246 object is actually a vector whose four elements are listed below.
249 A list of channel names this user is participating.
252 Connection information of this user, set in "<user>@<host>" format.
255 An alist which represents modes of this user.
258 A flag represent whether this user is AWAY.
260 **** The Mediator pattern
262 The riece-naming module is used to manage relationships between
263 channels and users. It utilizes the Mediator design pattern.
265 Using the riece-naming module allows to safely access to the namespace
266 rather than directly connects riece-channel/riece-user objects.
268 The riece-naming module provides the following functions.
270 - riece-naming-assert-join user-name channel-name
271 Assert that a user is a member of a channel.
273 - riece-naming-assert-part user-name channel-name
274 Assert that a user is no longer a member of a channel.
276 - riece-naming-assert-rename old-name new-name
277 Assert that a user changed his nickname.
281 There is a mechanism to connect events and display objects (windows,
282 buffers, and modeline indicators). This is done by signals.
284 When it is needed to redraw, a signal is emitted. The concept of
285 signals is corresponding to signals in generic window system toolkit
288 To emit a signal, use riece-emit-signal.
290 - riece-emit-signal signal-name &rest args
291 Emit a signal named signal-name with args.
293 To define a function called when a signal is emitted, use
294 riece-connect-signal.
296 - riece-connect-signal signal-name slot-function &optional
297 filter-function handback
299 Give a signal a slot-function. The slot-function gets two
300 arguments: the signal object itself and a handback object given as
301 the fourth argument of riece-connect-signal.
303 If the third argument filter-function is specified, the
304 slot-function is called conditionally. The filter-function gets the
305 signal object and returns nil or t. If the return value is nil, the
306 slot-function is not called.
308 To access to a signal object, use the following functions.
310 - riece-signal-name signal
311 Return the name of a signal.
314 Return the data of a signal.
316 Below is a list of signal names reserved.
318 - channel-list-changed
319 Need update the channel list.
322 Need update the user list.
323 (This signal gets a riece-identity object as an argument which
324 represents the channel.)
327 A user selected another channel.
329 - user-joined-channel
330 A user joined a channel.
331 (This signal gets two riece-identity objects as arguments
332 corresponding to the user and the channel respectively.)
335 A user left a channel.
336 (This signal gets two riece-identity objects as arguments
337 corresponding to the user and the channel respectively.)
340 A user changed his nickname.
341 (This signal gets two riece-identity objects as arguments
342 corresponding to the old and the new nickname respectively.)
345 A user changed his AWAY status.
346 (This signal gets a riece-identity object as an argument which
347 represents the user.)
349 - user-operator-changed
350 A user changed his IRC operator status.
351 (This signal gets a riece-identity object as an argument which
352 represents the user.)
354 - channel-topic-changed
355 A topic of a channel changed.
356 (This signal gets a riece-identity object as an argument which
357 represents the channel.)
359 - channel-modes-changed
360 Modes of a channel changed.
361 (This signal gets a riece-identity object as an argument which
362 represents the channel.)
364 - channel-operators-changed
365 A list of operators in a channel changed.
366 (This signal gets a riece-identity object as an argument which
367 represents the channel.)
369 - channel-speakers-changed
370 A list of users who have the right to speak in a channel changed.
371 (This signal gets a riece-identity object as an argument which
372 represents the channel.)
374 - buffer-freeze-changed
375 A buffer is frozen or unfrozen.
376 (This signal gets a buffer as an argument.)
380 Elisp modules that satisfy add-on spec should provide the following
383 - <module-name>-requires (optional)
384 Return a list of names of other add-ons this add-on depends.
386 - <module-name>-insinuate
387 Called on initialization of this module.
389 - <module-name>-uninstall (optional)
390 Called on uninstallation of this module.
392 - <module-name>-enable (optional)
393 Called when this add-on is enabled.
395 - <module-name>-disable (optional)
396 Called when this add-on is disabled.
398 It is recommended to set short explanation of the add-on to
399 <module-name>-description variable which is displayed on add-on
400 listing shown up by C-c ^ (M-x riece-command-list-addons).
402 To see the add-on's enabled/disabled status, check riece-addon-enabled
403 property set on <module-name> symbol.
405 Riece does the following procedure on add-ons when startup.
407 (1) Load add-ons listed in the riece-addons variable.
409 (2) Call <module-name>-requires on each add-on (if exists) and build a
412 (3) Sort the dependency graph.
414 (4) Call <module-name>-insinuate on each add-on in order of the
417 (5) Call <module-name>-enable on each add-on, iff it supports
418 enabling/disabling and is not disabled explicitly.
420 Add-ons are loaded from directories listed in load-path, or from
425 There are hooks called "handler hooks " which have special meaning in
426 Riece. Handler hooks are called before/after processing IRC messages.
428 - riece-<message>-hook
429 Called before processing an IRC message.
431 - riece-after-<message>-hook
432 Called after processing an IRC message.
434 Where <message> is a type of IRC message and consists only lowercase
437 If riece-<message>-hook returns non-nil, <message> is not processed.
438 In this case riece-after-<message>-hook is not called.
440 Handler hooks gets two arguments corresponding to prefix and
441 parameters in RFC2812.