3 This document is for Riece developers. The information necessary for
4 Riece development is explained (i.e. its development process and the
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. It is necessary to set
13 riece-debug to t before preparing a bug report.
17 If the riece-debug variable is set to t, Riece begins to collect
18 debugging information in *Debug* buffer. Interactions with IRC
19 servers are stored in " *IRC*<IRC-server-name>" buffers. Note that
20 these buffers have names starting with a whitespace character (" ").
22 ** Joining the development
24 To join the development, send us a patch or an add-on.
28 Development of Riece uses CVS. Latest developing version is available
29 at CVS. Please note that the version from CVS may NOT be reliable,
30 and you can only use it at your own risk. We may ignore bug reports
31 for that version. The instruction to access the CVS server is below.
33 (1) logging in to anonymous CVS server
35 cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
36 CVS password: [CR] # NULL string
40 cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout riece
42 (3) generate configure script
46 You will need newer version of GNU Automake.
52 Riece consists of many elisp modules listed below, ordered by the
53 number of dependencies they have.
56 This module defines global variables.
59 This module defines user options.
62 This module defines the version of Riece.
65 This module provides functions which support character code conversions.
68 This module provides functions which support tab completion feature
72 This module manages add-ons.
75 This module manages modes of riece-channel/riece-user objects.
78 This module defines the riece-identity object type which represents
79 global names of riece-channel/riece-user objects.
82 This module defines the riece-channel object type.
85 This module defines the riece-user object type.
88 This module provides miscellaneous functions.
91 This module defines the riece-signal object type used to manage
95 This module manages window layouts.
98 This module manages display events.
101 This module manages connections to IRC servers.
104 This module is a so called the Mediator design pattern. It knows
105 relationships of riece-channel/riece-user objects.
108 This module defines the riece-message object type.
111 This module only provides the process filter function.
114 This module provides handler functions for IRC messages. These
115 functions are called from riece-filter.
118 This module provides handler functions for numeric replies whose
119 response codes are in 000 to 100 range. These handlers are called
123 This module provides handler functions for numeric replies whose
124 response codes are in 200 to 300 range. These handlers are called
128 This module provides handler functions for numeric replies whose
129 response codes are in 300 to 400 range. These handlers are called
133 This module provides handler functions for numeric replies whose
134 response codes are in 400 to 500 range. These handlers are called
138 This module provides handler functions for numeric replies whose
139 response codes are in 500 to 600 range. These handlers are called
143 This module provides user commands.
146 This module provides the binding for the IRC protocol.
149 This module is the entry point of M-x riece.
151 ** Namespace management
153 Riece is capable to connect to several IRC servers.
155 Riece has separate namespace (obarray) for each connection. These
156 namespaces can be accessed as buffer local variables of process
159 *** Obtaining server buffer
161 To access to the buffer local variables of process buffer, it is
162 needed to distinguish process object of each connection by its name.
166 (1) checking the value of riece-overriding-server-name,
168 (2) checking the value of riece-server-name,
169 (If the variable riece-server-name is local to the current buffer,
170 you are already in the process buffer.)
172 (3) or parsing riece-identity objects
174 Once you get the name of the IRC server, you can get the process
175 object by passing the name to the function riece-server-process.
177 *** riece-identity objects
179 A riece-identity object represents a name of a channel/user. It is
180 used to distinguish a channel/user among several servers.
182 A riece-identity object is actually a vector, which consists of two
183 elements listed below.
186 A channel/user name local to an IRC server.
189 The name of the IRC server.
191 Methods to manipulate riece-identity object are listed below.
193 - riece-make-identity prefix &optional server
194 Create a new riece-identity object. If the server argument is
195 omitted, it sets the server part to the value returned by the
196 riece-find-server-name function.
198 - riece-identity-prefix identity
199 Return the prefix element from the given riece-identity object.
201 - riece-identity-server identity
202 Return the server element from the given riece-identity object.
204 - riece-identity-equal ident1 ident2
205 Return t, if two riece-identity objects are equal.
207 - riece-identity-equal-no-server ident1 ident2
208 Return t, if two riece-identity objects are equal. This function
209 only consider a prefix part of a riece-identity object.
211 - riece-identity-member elt list
212 Return non-nil if a riece-identity object is an element of a list.
214 *** Channels and users
216 A riece-channel object provides an abstraction of a channel.
217 Likewise, a riece-user object provides an abstraction of a user.
219 **** riece-channel objects
221 A riece-channel object has many information about a channel. A
222 riece-channel object is actually a vector whose seven elements are listed
226 A list of nicknames which are of users in this channel.
229 A list of nicknames which are of channel operators in this channel.
232 A list of nicknames which are of users who have the right to speak
236 An alist which represents modes of this channel.
239 A list of patterns set by MODE +b.
242 A list of patterns set by MODE +I.
245 A list of patterns set by MODE +e.
247 **** riece-user objects
249 A riece-user object has many information about a user. A riece-user
250 object is actually a vector whose four elements are listed below.
253 A list of channel names this user is participating.
256 Connection information of this user, set in "<user>@<host>" format.
259 An alist which represents modes of this user.
262 A flag represent whether this user is AWAY.
264 **** The Mediator pattern
266 The riece-naming module is used to manage relationships between
267 channels and users. It utilizes the Mediator design pattern.
269 Using the riece-naming module allows to safely access to the namespace
270 rather than directly connects riece-channel/riece-user objects.
272 The riece-naming module provides the following functions.
274 - riece-naming-assert-join user-name channel-name
275 Assert that a user is a member of a channel.
277 - riece-naming-assert-part user-name channel-name
278 Assert that a user is no longer a member of a channel.
280 - riece-naming-assert-rename old-name new-name
281 Assert that a user changed his nickname.
285 There is a mechanism to connect events and display objects (windows,
286 buffers, and modeline indicators). This is done by signals.
288 When it is needed to redraw, a signal is emitted. The concept of
289 signals is corresponding to signals in generic window system toolkit
292 To emit a signal, use riece-emit-signal.
294 - riece-emit-signal signal-name &rest args
295 Emit a signal named signal-name with args.
297 To define a function called when a signal is emitted, use
298 riece-connect-signal.
300 - riece-connect-signal signal-name slot-function &optional
301 filter-function handback
303 Give a signal a slot-function. The slot-function gets two
304 arguments: the signal object itself and a handback object given as
305 the fourth argument of riece-connect-signal.
307 If the third argument filter-function is specified, the
308 slot-function is called conditionally. The filter-function gets the
309 signal object and returns nil or t. If the return value is nil, the
310 slot-function is not called.
312 To access to a signal object, use the following functions.
314 - riece-signal-name signal
315 Return the name of a signal.
318 Return the data of a signal.
320 Below is a list of signal names reserved.
322 - channel-list-changed
323 Need update the channel list.
326 Need update the user list.
327 (This signal gets a riece-identity object as an argument which
328 represents the channel.)
331 A user selected another channel.
333 - user-joined-channel
334 A user joined a channel.
335 (This signal gets two riece-identity objects as arguments
336 corresponding to the user and the channel respectively.)
339 A user left a channel.
340 (This signal gets two riece-identity objects as arguments
341 corresponding to the user and the channel respectively.)
344 A user changed his nickname.
345 (This signal gets two riece-identity objects as arguments
346 corresponding to the old and the new nickname respectively.)
349 A user changed his AWAY status.
350 (This signal gets a riece-identity object as an argument which
351 represents the user.)
353 - user-operator-changed
354 A user changed his IRC operator status.
355 (This signal gets a riece-identity object as an argument which
356 represents the user.)
358 - channel-topic-changed
359 A topic of a channel changed.
360 (This signal gets a riece-identity object as an argument which
361 represents the channel.)
363 - channel-modes-changed
364 Modes of a channel changed.
365 (This signal gets a riece-identity object as an argument which
366 represents the channel.)
368 - channel-operators-changed
369 A list of operators in a channel changed.
370 (This signal gets a riece-identity object as an argument which
371 represents the channel.)
373 - channel-speakers-changed
374 A list of users who have the right to speak in a channel changed.
375 (This signal gets a riece-identity object as an argument which
376 represents the channel.)
378 - buffer-freeze-changed
379 A buffer is frozen or unfrozen.
380 (This signal gets a buffer as an argument.)
384 Elisp modules that satisfy add-on spec should provide the following
387 - <module-name>-requires (optional)
388 Return a list of names of other add-ons this add-on depends.
390 - <module-name>-insinuate
391 Called on initialization of this module.
393 - <module-name>-uninstall (optional)
394 Called on uninstallation of this module.
396 - <module-name>-enable (optional)
397 Called when this add-on is enabled.
399 - <module-name>-disable (optional)
400 Called when this add-on is disabled.
402 It is recommended to set short explanation of the add-on to
403 <module-name>-description variable which is displayed on add-on
404 listing shown up by C-c ^ (M-x riece-command-list-addons).
406 To see the add-on's enabled/disabled status, check riece-addon-enabled
407 property set on <module-name> symbol.
409 Riece does the following procedure on add-ons when startup.
411 (1) Load add-ons listed in the riece-addons variable.
413 (2) Call <module-name>-requires on each add-on (if exists) and build a
416 (3) Sort the dependency graph.
418 (4) Call <module-name>-insinuate on each add-on in order of the
421 (5) Call <module-name>-enable on each add-on, iff it supports
422 enabling/disabling and is not disabled explicitly.
424 Add-ons are loaded from directories listed in load-path, or from
429 There are hooks called "handler hooks " which have special meaning in
430 Riece. Handler hooks are called before/after processing IRC messages.
432 - riece-<message>-hook
433 Called before processing an IRC message.
435 - riece-after-<message>-hook
436 Called after processing an IRC message.
438 Where <message> is a type of IRC message and consists only lowercase
441 If riece-<message>-hook returns non-nil, <message> is not processed.
442 In this case riece-after-<message>-hook is not called.
444 Handler hooks gets two arguments corresponding to prefix and
445 parameters in RFC2812.