3 This document is for Riece developers or those who are interested in
6 The main topics explained here are the development process and the
9 Even though this document describes how to build the source code from
10 the CVS, you should notice that it is intentional that we don't put
11 the instruction on the Web page--that is, pointless complaints about
12 development versions are _unwelcome_ to us.
14 If you are a beginning user, who just wants to try the "newer" product
15 from the CVS, abandon the bad idea and stick on the released version.
21 You can create a template of a bug report by `M-x
22 riece-submit-bug-report'. This command assumes that riece-debug is t.
24 If riece-debug is t, "*Debug*" buffer will have debugging information.
25 Also, interactions with IRC servers will be written to "
26 *IRC*<IRC-server-name>" buffers. Note that these buffers have a name
27 starting with a whitespace character (" ").
31 If you write an add-on or a patch, send it to us. If it is useful, we
32 may incorporate it into the development source code.
34 ** Getting the development source code
36 Again, use the released version if you are a beginning user and not
37 willing to become a developer.
39 The development of Riece uses CVS. The latest development version is
40 available from cvs.m17n.org. The instructions to obtain and build the
41 source from the CVS are below.
45 cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout riece
47 You can specify a tag in front of the module name.
49 (2) generate configure script
53 Note that "autoreconf" is not "autoconf".
59 Riece consists of many elisp modules listed below, ordered by the
60 number of dependencies they have.
63 This module defines global variables.
66 This module defines user options.
69 This module defines the version of Riece.
72 This module provides functions which support character code conversions.
75 This module provides functions which support tab completion feature
79 This module manages add-ons.
82 This module manages modes of riece-channel/riece-user objects.
85 This module defines the riece-identity object type which represents
86 global names of riece-channel/riece-user objects.
89 This module defines the riece-channel object type.
92 This module defines the riece-user object type.
95 This module provides miscellaneous functions.
98 This module defines the riece-signal object type used to manage
102 This module manages window layouts.
105 This module manages display events.
108 This module manages connections to IRC servers.
111 This module is a so called the Mediator design pattern. It knows
112 relationships of riece-channel/riece-user objects.
115 This module defines the riece-message object type.
118 This module only provides the process filter function.
121 This module provides handler functions for IRC messages. These
122 functions are called from riece-filter.
125 This module provides handler functions for numeric replies whose
126 response codes are in 000 to 100 range. These handlers are called
130 This module provides handler functions for numeric replies whose
131 response codes are in 200 to 300 range. These handlers are called
135 This module provides handler functions for numeric replies whose
136 response codes are in 300 to 400 range. These handlers are called
140 This module provides handler functions for numeric replies whose
141 response codes are in 400 to 500 range. These handlers are called
145 This module provides handler functions for numeric replies whose
146 response codes are in 500 to 600 range. These handlers are called
150 This module provides user commands.
153 This module provides the binding for the IRC protocol.
156 This module is the entry point of M-x riece.
158 ** Namespace management
160 Riece is capable to connect to several IRC servers.
162 Riece has separate namespace (obarray) for each connection. These
163 namespaces can be accessed as buffer local variables of process
166 *** Obtaining server buffer
168 To access to the buffer local variables of process buffer, it is
169 needed to distinguish process object of each connection by its name.
173 (1) checking the value of riece-overriding-server-name,
175 (2) checking the value of riece-server-name,
176 (If the variable riece-server-name is local to the current buffer,
177 you are already in the process buffer.)
179 (3) or parsing riece-identity objects
181 Once you get the name of the IRC server, you can get the process
182 object by passing the name to the function riece-server-process.
184 *** riece-identity objects
186 A riece-identity object represents a name of a channel/user. It is
187 used to distinguish a channel/user among several servers.
189 A riece-identity object is actually a vector, which consists of two
190 elements listed below.
193 A channel/user name local to an IRC server.
196 The name of the IRC server.
198 Methods to manipulate riece-identity object are listed below.
200 - riece-make-identity prefix &optional server
201 Create a new riece-identity object. If the server argument is
202 omitted, it sets the server part to the value returned by the
203 riece-find-server-name function.
205 - riece-identity-prefix identity
206 Return the prefix element from the given riece-identity object.
208 - riece-identity-server identity
209 Return the server element from the given riece-identity object.
211 - riece-identity-equal ident1 ident2
212 Return t, if two riece-identity objects are equal.
214 - riece-identity-equal-no-server ident1 ident2
215 Return t, if two riece-identity objects are equal. This function
216 only consider a prefix part of a riece-identity object.
218 - riece-identity-member elt list
219 Return non-nil if a riece-identity object is an element of a list.
221 *** Channels and users
223 A riece-channel object provides an abstraction of a channel.
224 Likewise, a riece-user object provides an abstraction of a user.
226 **** riece-channel objects
228 A riece-channel object has many information about a channel. A
229 riece-channel object is actually a vector whose seven elements are listed
233 A list of nicknames which are of users in this channel.
236 A list of nicknames which are of channel operators in this channel.
239 A list of nicknames which are of users who have the right to speak
243 An alist which represents modes of this channel.
246 A list of patterns set by MODE +b.
249 A list of patterns set by MODE +I.
252 A list of patterns set by MODE +e.
254 **** riece-user objects
256 A riece-user object has many information about a user. A riece-user
257 object is actually a vector whose four elements are listed below.
260 A list of channel names this user is participating.
263 Connection information of this user, set in "<user>@<host>" format.
266 An alist which represents modes of this user.
269 A flag represent whether this user is AWAY.
271 **** The Mediator pattern
273 The riece-naming module is used to manage relationships between
274 channels and users. It utilizes the Mediator design pattern.
276 Using the riece-naming module allows to safely access to the namespace
277 rather than directly connects riece-channel/riece-user objects.
279 The riece-naming module provides the following functions.
281 - riece-naming-assert-join user-name channel-name
282 Assert that a user is a member of a channel.
284 - riece-naming-assert-part user-name channel-name
285 Assert that a user is no longer a member of a channel.
287 - riece-naming-assert-rename old-name new-name
288 Assert that a user changed his nickname.
292 There is a mechanism to connect events and display objects (windows,
293 buffers, and modeline indicators). This is done by signals.
295 When it is needed to redraw, a signal is emitted. The concept of
296 signals is corresponding to signals in generic window system toolkit
299 To emit a signal, use riece-emit-signal.
301 - riece-emit-signal signal-name &rest args
302 Emit a signal named signal-name with args.
304 To define a function called when a signal is emitted, use
305 riece-connect-signal.
307 - riece-connect-signal signal-name slot-function &optional
308 filter-function handback
310 Give a signal a slot-function. The slot-function gets two
311 arguments: the signal object itself and a handback object given as
312 the fourth argument of riece-connect-signal.
314 If the third argument filter-function is specified, the
315 slot-function is called conditionally. The filter-function gets the
316 signal object and returns nil or t. If the return value is nil, the
317 slot-function is not called.
319 To access to a signal object, use the following functions.
321 - riece-signal-name signal
322 Return the name of a signal.
325 Return the data of a signal.
327 Below is a list of signal names reserved.
329 - channel-list-changed
330 Need update the channel list.
333 Need update the user list.
334 (This signal gets a riece-identity object as an argument which
335 represents the channel.)
338 A user selected another channel.
340 - user-joined-channel
341 A user joined a channel.
342 (This signal gets two riece-identity objects as arguments
343 corresponding to the user and the channel respectively.)
346 A user left a channel.
347 (This signal gets two riece-identity objects as arguments
348 corresponding to the user and the channel respectively.)
351 A user changed his nickname.
352 (This signal gets two riece-identity objects as arguments
353 corresponding to the old and the new nickname respectively.)
356 A user changed his AWAY status.
357 (This signal gets a riece-identity object as an argument which
358 represents the user.)
360 - user-operator-changed
361 A user changed his IRC operator status.
362 (This signal gets a riece-identity object as an argument which
363 represents the user.)
365 - channel-topic-changed
366 A topic of a channel changed.
367 (This signal gets a riece-identity object as an argument which
368 represents the channel.)
370 - channel-modes-changed
371 Modes of a channel changed.
372 (This signal gets a riece-identity object as an argument which
373 represents the channel.)
375 - channel-operators-changed
376 A list of operators in a channel changed.
377 (This signal gets a riece-identity object as an argument which
378 represents the channel.)
380 - channel-speakers-changed
381 A list of users who have the right to speak in a channel changed.
382 (This signal gets a riece-identity object as an argument which
383 represents the channel.)
385 - buffer-freeze-changed
386 A buffer is frozen or unfrozen.
387 (This signal gets a buffer as an argument.)
391 Elisp modules that satisfy add-on spec should provide the following
394 - <module-name>-requires (optional)
395 Return a list of names of other add-ons this add-on depends.
397 - <module-name>-insinuate
398 Called on initialization of this module.
400 - <module-name>-uninstall (optional)
401 Called on uninstallation of this module.
403 - <module-name>-enable (optional)
404 Called when this add-on is enabled.
406 - <module-name>-disable (optional)
407 Called when this add-on is disabled.
409 It is recommended to set short explanation of the add-on to
410 <module-name>-description variable which is displayed on add-on
411 listing shown up by C-c ^ (M-x riece-command-list-addons).
413 To see the add-on's enabled/disabled status, check riece-addon-enabled
414 property set on <module-name> symbol.
416 Riece does the following procedure on add-ons when startup.
418 (1) Load add-ons listed in the riece-addons variable.
420 (2) Call <module-name>-requires on each add-on (if exists) and build a
423 (3) Sort the dependency graph.
425 (4) Call <module-name>-insinuate on each add-on in order of the
428 (5) Call <module-name>-enable on each add-on, iff it supports
429 enabling/disabling and is not disabled explicitly.
431 Add-ons are loaded from directories listed in load-path, or from
436 There are hooks called "handler hooks " which have special meaning in
437 Riece. Handler hooks are called before/after processing IRC messages.
439 - riece-<message>-hook
440 Called before processing an IRC message.
442 - riece-after-<message>-hook
443 Called after processing an IRC message.
445 Where <message> is a type of IRC message and consists only lowercase
448 If riece-<message>-hook returns non-nil, <message> is not processed.
449 In this case riece-after-<message>-hook is not called.
451 Handler hooks gets two arguments corresponding to prefix and
452 parameters in RFC2812.