3 This document is for Riece developers. The information necessary for
4 Riece development is explaind (i.e. its development process and the
11 You can create a bug report by clicking the "bug" button in a toolbar,
12 or M-x riece-submit-bug-report. It is necessary to set riece-debug to
13 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.
20 And also, interactions with IRC servers are stored in
21 " *IRC*<IRC-server-name>" buffers. Note that the buffer names start
22 with a whitespace character (" ").
24 ** Joining the development
26 To join the development, send us a patch or an add-on.
30 Development of Riece uses CVS. Latest developing version is available
31 at CVS. Please note that the newest development version from CVS may
32 _not_ be reliable. You can only use it at your own risk. We may
33 ignore bug reports for that version.
35 (1) logging in to anonymous CVS server
37 cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
38 CVS password: [CR] # NULL string
42 cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout riece
44 (3) generate configure script
48 You will need newer version of GNU Automake.
54 Riece consists of elisp modules listed below, ordered by the number of
58 This module defines global variables.
61 This module defines user options.
64 This module defines the version of Riece.
67 This module provides functions which support code conversions.
71 This module provides functions which support tab completion in a
75 This module manages add-ons.
78 This module manages modes of riece-channel/riece-user objects.
81 This module defines the riece-identity object type which represents
82 global names of riece-channel/riece-user objects.
85 This module defines the riece-channel object type.
88 This module defines the riece-user object type.
91 This module provides miscellaneous functions.
94 This module manages routing display signals.
97 This module manages window layouts.
100 This module manages display events.
103 This module manages connections to IRC servers.
106 This module is a so called Mediator pattern which knows relations of
110 This module defines the riece-message object type.
113 This module defines the process filter.
116 This module provides handler definitions for IRC messages. These
117 handlers are called from riece-filter.
120 This module provides handler definitions for numeric replies whose
121 response codes are in 000 to 100 range. These handlers are called
125 This module provides handler definitions for numeric replies whose
126 response codes are in 200 to 300 range. These handlers are called
130 This module provides handler definitions for numeric replies whose
131 response codes are in 300 to 400 range. These handlers are called
135 This module provides handler definitions for numeric replies whose
136 response codes are in 400 to 500 range. These handlers are called
140 This module provides handler definitions for numeric replies whose
141 response codes are in 500 to 600 range. These handlers are called
145 This module provides commands.
148 This module sets up process-filter for the IRC protocol.
151 This module is the entry point of M-x riece.
153 ** Namespace management
155 Riece is capable to connect to several IRC servers.
157 Riece has separate namespace (obarray) for each connection. These
158 namespaces can be accessed as buffer local variables of process
161 *** Obtaining server buffer
163 To access to the buffer local variables of process buffer, it is
164 needed to distinguish process object of each connection by its name.
168 (1) checking the value of riece-overrinding-server-name,
170 (2) checking the value of riece-server-name,
171 (If the variable riece-server-name is local to the current buffer,
172 you are already in the process buffer.)
174 (3) or parsing riece-identity objects
176 Once you get the name of the IRC server, you can get the process
177 object by passing the name to the function riece-server-process.
179 *** riece-identity objects
181 A riece-identity object represents a name of a channel/user. It is
182 used to distinguish a channel/user among several servers.
184 A riece-identity object is actually a vector, which consists of two
185 elements listed below.
188 A channel/user name local to an IRC server.
191 The name of the IRC server.
193 Methods to manipulate riece-identity object are listed below.
195 - riece-make-identity prefix &optional server
196 Create a new riece-identity object. If the server argument is
197 omitted, it sets the server part to the value returned by the
198 riece-find-server-name function.
200 - riece-identity-prefix identity
201 Return the prefix element from the given riece-identity object.
203 - riece-identity-server identity
204 Return the server element from the given riece-identity object.
206 - riece-identity-equal ident1 ident2
207 Return t, if two riece-identity objects are equal.
209 - riece-identity-equal-no-server ident1 ident2
210 Return t, if two riece-identity objects are equal. This function
211 only consider a prefix part of a riece-identity object.
213 - riece-identity-member elt list
214 Return non-nil if a riece-identity object is an element of a list.
216 *** Channels and users
218 A riece-channel object provides an abstraction of a channel.
219 Likewise, a riece-user object provides an abstraction of a user.
221 **** riece-channel objects
223 A riece-channel object has many information about a channel. A
224 riece-channel object is actually a vector whose seven elements are listed
228 A list of nicknames which are of users in this channel.
231 A list of nicknames which are of channel operators in this channel.
234 A list of nicknames which are of users who have the right to speak
238 An alist which represents modes of this channel.
241 A list of patterns set by MODE +b.
244 A list of patterns set by MODE +I.
247 A list of patterns set by MODE +e.
249 **** riece-user objects
251 A riece-user object has many information about a user. A riece-user
252 object is actually a vector whose four elements are listed below.
255 A list of channel names this user is participating.
258 Connection information of this user, set in "<user>@<host>" format.
261 An alist which represents modes of this user.
264 A flag represent whether this user is AWAY.
266 **** The Mediator pattern
268 The riece-naming module is used to manage relationships between
269 channels and users. It utilizes the Mediator design pattern.
271 Using the riece-naming module allows to safely access to the namespace
272 rather than directly connects riece-channel/riece-user objects.
274 The riece-naming module provides the following functions.
276 - riece-naming-assert-join user-name channel-name
277 Assert that a user is a member of a channel.
279 - riece-naming-assert-part user-name channel-name
280 Assert that a user is no longer a member of a channel.
282 - riece-naming-assert-rename old-name new-name
283 Assert that a user changed his nickname.
287 There is a mechanism to connect events and display objects (windows,
288 buffers, and modeline indicators). This is done by signals.
290 When it is needed to redraw, a signal is emitted. The concept of
291 signals is corresponding to signals in generic window system toolkit
294 To emit a signal, use riece-emit-signal.
296 - riece-emit-signal signal-name &rest args
297 Emit a signal named signal-name with args.
299 To define a function called when a signal is emitted, use
300 riece-connect-signal.
302 - riece-connect-signal signal-name slot-function &optional
303 filter-function handback
305 Give a signal a slot-function. The slot-function gets two
306 arguments: the signal object itself and a handback object given as
307 the fourth argument of riece-connect-signal.
309 If the third argument filter-function is specified, the
310 slot-function is called conditionaly. The filter-function gets the
311 signal object and returns nil or t. If the return value is nil, the
312 slot-function is not called.
314 To access to a signal object, use the following functions.
316 - riece-signal-name signal
317 Return the name of a signal.
320 Return the data of a signal.
322 Below is a list of signal names reserved.
324 - channel-list-changed
325 Need update the channel list.
328 Need update the user list.
329 (This signal gets a riece-identity object as an argument which
330 represents the channel.)
333 A user selected another channel.
335 - user-joined-channel
336 A user joined a channel.
337 (This signal gets two riece-identity objects as arguments
338 corresponding to the user and the channel respectively.)
341 A user left a channel.
342 (This signal gets two riece-identity objects as arguments
343 corresponding to the user and the channel respectively.)
346 A user changed his nickname.
347 (This signal gets two riece-identity objects as arguments
348 corresponding to the old and the new nickname respectively.)
351 A user changed his AWAY status.
352 (This signal gets a riece-identity object as an argument which
353 represents the user.)
355 - user-operator-changed
356 A user changed his IRC operator status.
357 (This signal gets a riece-identity object as an argument which
358 represents the user.)
360 - channel-topic-changed
361 A topic of a channel changed.
362 (This signal gets a riece-identity object as an argument which
363 represents the channel.)
365 - channel-modes-changed
366 Modes of a channel changed.
367 (This signal gets a riece-identity object as an argument which
368 represents the channel.)
370 - channel-operators-changed
371 A list of operators in a channel changed.
372 (This signal gets a riece-identity object as an argument which
373 represents the channel.)
375 - channel-speakers-changed
376 A list of users who have the right to speak in a channel changed.
377 (This signal gets a riece-identity object as an argument which
378 represents the channel.)
380 - buffer-freeze-changed
381 A buffer is frozen or unfrozen.
382 (This signal gets a buffer as an argument.)
386 Elisp modules that satisfy add-on spec should provide the following
389 - <module-name>-requires
390 Return a list of names of other add-ons this add-on depends. (optional)
392 - <module-name>-insinuate
393 Called on initialization of this module.
395 It is recommended to set short explanation of the add-on to
396 <module-name>-description variable which is displayed on add-on
397 listing shown up by C-c ^ (M-x riece-command-list-addons).
399 Add-ons that support enabling/disabling set the current status to
400 <module-name>-enabled variable. If this variable is nil, the add-on
401 is regarded as currently disabled. In addition, the add-on must
402 provide the following two functions.
404 - <module-name>-enable
405 Called to enable this add-on.
407 - <module-name>-disable
408 Called to disable this add-on.
410 Riece does the following process when startup.
412 (1) Load add-ons listed in the riece-addons variable.
414 (2) Call <module-name>-requires on each add-on (if exists) and build a
417 (3) Sort the dependency graph.
419 (4) Call <module-name>-insinuate on each add-on in order of the
422 (5) Call <module-name>-enable on each add-on, iff it supports
423 enabling/disabling and is not disabled explicitly.
425 Add-ons are loaded from directories listed in load-path, or from
430 There are hooks called "handler hooks " which have special meaning in
431 Riece. Handler hooks are called before/after processing IRC messages.
433 - riece-<message>-hook
434 Called before processing an IRC message.
436 - riece-after-<message>-hook
437 Called after processing an IRC message.
439 Where <message> is a type of IRC message and consists only lowercase
442 If riece-<message>-hook returns non-nil, <message> is not processed.
443 In this case riece-after-<message>-hook is not called.
445 Handler hooks gets two arguments corresponding to prefix and
446 parameters in RFC2812.