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
13 If you find a bug, please file it at
14 https://savannah.nongnu.org/bugs/?group=riece
18 If you write an add-on or a patch, send it to us. If it is useful, we
19 may incorporate it into the development source code.
21 ** Getting the development source code
23 The development of Riece uses Git. The latest development version is
24 available from git.sv.gnu.org.
26 NOTE: If you are a beginning user, who just wants to try the "newer"
27 version, stick on the latest released version. Pointless complaints
28 about development versions are unwelcome to us.
30 The instructions to obtain and build the source from Git are below.
34 git clone git://git.sv.gnu.org/riece.git
36 (2) generate configure script
40 Note that "autoreconf" is not "autoconf".
46 Riece consists of many elisp modules listed below, ordered by the
47 number of dependencies they have.
50 This module defines global variables.
53 This module defines user options.
56 This module defines the version of Riece.
59 This module provides functions which support character code conversions.
62 This module provides functions which support tab completion feature
66 This module manages add-ons.
69 This module manages modes of riece-channel/riece-user objects.
72 This module defines the riece-identity object type which represents
73 global names of riece-channel/riece-user objects.
76 This module defines the riece-channel object type.
79 This module defines the riece-user object type.
82 This module provides miscellaneous functions.
85 This module defines the riece-signal object type used to manage
89 This module manages window layouts.
92 This module manages display events.
95 This module manages connections to IRC servers.
98 This module is a so called the Mediator design pattern. It knows
99 relationships of riece-channel/riece-user objects.
102 This module defines the riece-message object type.
105 This module only provides the process filter function.
108 This module provides handler functions for IRC messages. These
109 functions are called from riece-filter.
112 This module provides handler functions for numeric replies whose
113 response codes are in 000 to 100 range. These handlers are called
117 This module provides handler functions for numeric replies whose
118 response codes are in 200 to 300 range. These handlers are called
122 This module provides handler functions for numeric replies whose
123 response codes are in 300 to 400 range. These handlers are called
127 This module provides handler functions for numeric replies whose
128 response codes are in 400 to 500 range. These handlers are called
132 This module provides handler functions for numeric replies whose
133 response codes are in 500 to 600 range. These handlers are called
137 This module provides user commands.
140 This module provides the binding for the IRC protocol.
143 This module is the entry point of M-x riece.
145 ** Namespace management
147 Riece is capable to connect to several IRC servers.
149 Riece has separate namespace (obarray) for each connection. These
150 namespaces can be accessed as buffer local variables of process
153 *** Obtaining server buffer
155 To access to the buffer local variables of process buffer, it is
156 needed to distinguish process object of each connection by its name.
160 (1) checking the value of riece-overriding-server-name,
162 (2) checking the value of riece-server-name,
163 (If the variable riece-server-name is local to the current buffer,
164 you are already in the process buffer.)
166 (3) or parsing riece-identity objects
168 Once you get the name of the IRC server, you can get the process
169 object by passing the name to the function riece-server-process.
171 *** riece-identity objects
173 A riece-identity object represents a name of a channel/user. It is
174 used to distinguish a channel/user among several servers.
176 A riece-identity object is actually a vector, which consists of two
177 elements listed below.
180 A channel/user name local to an IRC server.
183 The name of the IRC server.
185 Methods to manipulate riece-identity object are listed below.
187 - riece-make-identity prefix &optional server
188 Create a new riece-identity object. If the server argument is
189 omitted, it sets the server part to the value returned by the
190 riece-find-server-name function.
192 - riece-identity-prefix identity
193 Return the prefix element from the given riece-identity object.
195 - riece-identity-server identity
196 Return the server element from the given riece-identity object.
198 - riece-identity-equal ident1 ident2
199 Return t, if two riece-identity objects are equal.
201 - riece-identity-equal-no-server ident1 ident2
202 Return t, if two riece-identity objects are equal. This function
203 only consider a prefix part of a riece-identity object.
205 - riece-identity-member elt list
206 Return non-nil if a riece-identity object is an element of a list.
208 *** Channels and users
210 A riece-channel object provides an abstraction of a channel.
211 Likewise, a riece-user object provides an abstraction of a user.
213 **** riece-channel objects
215 A riece-channel object has many information about a channel. A
216 riece-channel object is actually a vector whose seven elements are listed
220 A list of nicknames which are of users in this channel.
223 A list of nicknames which are of channel operators in this channel.
226 A list of nicknames which are of users who have the right to speak
230 An alist which represents modes of this channel.
233 A list of patterns set by MODE +b.
236 A list of patterns set by MODE +I.
239 A list of patterns set by MODE +e.
241 **** riece-user objects
243 A riece-user object has many information about a user. A riece-user
244 object is actually a vector whose four elements are listed below.
247 A list of channel names this user is participating.
250 Connection information of this user, set in "<user>@<host>" format.
253 An alist which represents modes of this user.
256 A flag represent whether this user is AWAY.
258 **** The Mediator pattern
260 The riece-naming module is used to manage relationships between
261 channels and users. It utilizes the Mediator design pattern.
263 Using the riece-naming module allows to safely access to the namespace
264 rather than directly connects riece-channel/riece-user objects.
266 The riece-naming module provides the following functions.
268 - riece-naming-assert-join user-name channel-name
269 Assert that a user is a member of a channel.
271 - riece-naming-assert-part user-name channel-name
272 Assert that a user is no longer a member of a channel.
274 - riece-naming-assert-rename old-name new-name
275 Assert that a user changed his nickname.
279 There is a mechanism to connect events and display objects (windows,
280 buffers, and modeline indicators). This is done by signals.
282 When it is needed to redraw, a signal is emitted. The concept of
283 signals is corresponding to signals in generic window system toolkit
286 To emit a signal, use riece-emit-signal.
288 - riece-emit-signal signal-name &rest args
289 Emit a signal named signal-name with args.
291 To define a function called when a signal is emitted, use
292 riece-connect-signal.
294 - riece-connect-signal signal-name slot-function &optional
295 filter-function handback
297 Give a signal a slot-function. The slot-function gets two
298 arguments: the signal object itself and a handback object given as
299 the fourth argument of riece-connect-signal.
301 If the third argument filter-function is specified, the
302 slot-function is called conditionally. The filter-function gets the
303 signal object and returns nil or t. If the return value is nil, the
304 slot-function is not called.
306 To access to a signal object, use the following functions.
308 - riece-signal-name signal
309 Return the name of a signal.
312 Return the data of a signal.
314 Below is a list of signal names reserved.
316 - channel-list-changed
317 Need update the channel list.
320 Need update the user list.
321 (This signal gets a riece-identity object as an argument which
322 represents the channel.)
325 A user selected another channel.
327 - user-joined-channel
328 A user joined a channel.
329 (This signal gets two riece-identity objects as arguments
330 corresponding to the user and the channel respectively.)
333 A user left a channel.
334 (This signal gets two riece-identity objects as arguments
335 corresponding to the user and the channel respectively.)
338 A user changed his nickname.
339 (This signal gets two riece-identity objects as arguments
340 corresponding to the old and the new nickname respectively.)
343 A user changed his AWAY status.
344 (This signal gets a riece-identity object as an argument which
345 represents the user.)
347 - user-operator-changed
348 A user changed his IRC operator status.
349 (This signal gets a riece-identity object as an argument which
350 represents the user.)
352 - channel-topic-changed
353 A topic of a channel changed.
354 (This signal gets a riece-identity object as an argument which
355 represents the channel.)
357 - channel-modes-changed
358 Modes of a channel changed.
359 (This signal gets a riece-identity object as an argument which
360 represents the channel.)
362 - channel-operators-changed
363 A list of operators in a channel changed.
364 (This signal gets a riece-identity object as an argument which
365 represents the channel.)
367 - channel-speakers-changed
368 A list of users who have the right to speak in a channel changed.
369 (This signal gets a riece-identity object as an argument which
370 represents the channel.)
372 - buffer-freeze-changed
373 A buffer is frozen or unfrozen.
374 (This signal gets a buffer as an argument.)
378 Elisp modules that satisfy add-on spec should provide the following
381 - <module-name>-requires (optional)
382 Return a list of names of other add-ons this add-on depends.
384 - <module-name>-insinuate
385 Called on initialization of this module.
387 - <module-name>-uninstall (optional)
388 Called on uninstallation of this module.
390 - <module-name>-enable (optional)
391 Called when this add-on is enabled.
393 - <module-name>-disable (optional)
394 Called when this add-on is disabled.
396 It is recommended to set short explanation of the add-on to
397 <module-name>-description variable which is displayed on add-on
398 listing shown up by C-c ^ (M-x riece-command-list-addons).
400 To see the add-on's enabled/disabled status, check riece-addon-enabled
401 property set on <module-name> symbol.
403 Riece does the following procedure on add-ons when startup.
405 (1) Load add-ons listed in the riece-addons variable.
407 (2) Call <module-name>-requires on each add-on (if exists) and build a
410 (3) Sort the dependency graph.
412 (4) Call <module-name>-insinuate on each add-on in order of the
415 (5) Call <module-name>-enable on each add-on, iff it supports
416 enabling/disabling and is not disabled explicitly.
418 Add-ons are loaded from directories listed in load-path, or from
423 There are hooks called "handler hooks " which have special meaning in
424 Riece. Handler hooks are called before/after processing IRC messages.
426 - riece-<message>-hook
427 Called before processing an IRC message.
429 - riece-after-<message>-hook
430 Called after processing an IRC message.
432 Where <message> is a type of IRC message and consists only lowercase
435 If riece-<message>-hook returns non-nil, <message> is not processed.
436 In this case riece-after-<message>-hook is not called.
438 Handler hooks gets two arguments corresponding to prefix and
439 parameters in RFC2812.