* riece-options.el (riece-data-directory): Use load-file-name.
[riece] / doc / HACKING
1 -*- mode: text -*-
2
3 This document is for Riece developers.  The information necessary for
4 Riece development is explained (i.e. its development process and the
5 internals.)
6
7 * Development process
8
9 ** Bug report
10
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.
14
15 ** Debug output
16
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 (" ").
21
22 ** Joining the development
23
24 To join the development, send us a patch or an add-on.
25
26 ** CVS
27
28 Development of Riece uses CVS.  Latest developing version is available
29 at CVS.  Please note that the newest development version from CVS may
30 NOT be reliable.  You can only use it at your own risk.  We may ignore
31 bug reports for that version.  The instruction to access the CVS
32 server is below.
33
34 (1) logging in to anonymous CVS server
35
36     cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
37     CVS password: [CR] # NULL string
38
39 (2) checkout modules
40
41     cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout riece
42
43 (3) generate configure script
44
45     autoreconf -f -i -v
46
47 You will need newer version of GNU Automake.
48
49 * Internals
50
51 ** Modules
52
53 Riece consists of many elisp modules listed below, ordered by the
54 number of dependencies they have.
55
56 - riece-globals
57   This module defines global variables.
58
59 - riece-options
60   This module defines user options.
61
62 - riece-version
63   This module defines the version of Riece.
64
65 - riece-coding
66   This module provides functions which support character code conversions.
67
68 - riece-complete
69   This module provides functions which support tab completion feature
70   in a mini buffer.
71
72 - riece-addon
73   This module manages add-ons.
74
75 - riece-mode
76   This module manages modes of riece-channel/riece-user objects.
77
78 - riece-identity
79   This module defines the riece-identity object type which represents
80   global names of riece-channel/riece-user objects.
81
82 - riece-channel
83   This module defines the riece-channel object type.
84
85 - riece-user
86   This module defines the riece-user object type.
87
88 - riece-misc
89   This module provides miscellaneous functions.
90
91 - riece-signal
92   This module defines the riece-signal object type used to manage
93   display events.
94
95 - riece-layout
96   This module manages window layouts.
97
98 - riece-display
99   This module manages display events.
100
101 - riece-server
102   This module manages connections to IRC servers.
103
104 - riece-naming
105   This module is a so called the Mediator design pattern.  It knows
106   relationships of riece-channel/riece-user objects.
107
108 - riece-message
109   This module defines the riece-message object type.
110
111 - riece-filter
112   This module only provides the process filter function.
113
114 - riece-handle
115   This module provides handler functions for IRC messages.  These
116   functions are called from riece-filter.
117
118 - riece-000
119   This module provides handler functions for numeric replies whose
120   response codes are in 000 to 100 range.  These handlers are called
121   from riece-filter.
122
123 - riece-200
124   This module provides handler functions for numeric replies whose
125   response codes are in 200 to 300 range.  These handlers are called
126   from riece-filter.
127
128 - riece-300
129   This module provides handler functions for numeric replies whose
130   response codes are in 300 to 400 range.  These handlers are called
131   from riece-filter.
132
133 - riece-400
134   This module provides handler functions for numeric replies whose
135   response codes are in 400 to 500 range.  These handlers are called
136   from riece-filter.
137
138 - riece-500
139   This module provides handler functions for numeric replies whose
140   response codes are in 500 to 600 range.  These handlers are called
141   from riece-filter.
142
143 - riece-commands
144   This module provides user commands.
145
146 - riece-irc
147   This module provides the binding for the IRC protocol.
148
149 - riece
150   This module is the entry point of M-x riece.
151
152 ** Namespace management
153
154 Riece is capable to connect to several IRC servers.
155
156 Riece has separate namespace (obarray) for each connection.  These
157 namespaces can be accessed as buffer local variables of process
158 buffer.
159
160 *** Obtaining server buffer
161
162 To access to the buffer local variables of process buffer, it is
163 needed to distinguish process object of each connection by its name.
164
165 It can be known by:
166
167 (1) checking the value of riece-overriding-server-name,
168
169 (2) checking the value of riece-server-name,
170     (If the variable riece-server-name is local to the current buffer,
171     you are already in the process buffer.)
172
173 (3) or parsing riece-identity objects
174
175 Once you get the name of the IRC server, you can get the process
176 object by passing the name to the function riece-server-process.
177
178 *** riece-identity objects
179
180 A riece-identity object represents a name of a channel/user.  It is
181 used to distinguish a channel/user among several servers.
182
183 A riece-identity object is actually a vector, which consists of two
184 elements listed below.
185
186 - prefix
187   A channel/user name local to an IRC server.
188
189 - server
190   The name of the IRC server.
191
192 Methods to manipulate riece-identity object are listed below.
193
194 - riece-make-identity prefix &optional server
195   Create a new riece-identity object.  If the server argument is
196   omitted, it sets the server part to the value returned by the
197   riece-find-server-name function.
198
199 - riece-identity-prefix identity
200   Return the prefix element from the given riece-identity object.
201
202 - riece-identity-server identity
203   Return the server element from the given riece-identity object.
204
205 - riece-identity-equal ident1 ident2
206   Return t, if two riece-identity objects are equal.
207
208 - riece-identity-equal-no-server ident1 ident2
209   Return t, if two riece-identity objects are equal.  This function
210   only consider a prefix part of a riece-identity object.
211
212 - riece-identity-member elt list
213   Return non-nil if a riece-identity object is an element of a list.
214
215 *** Channels and users
216
217 A riece-channel object provides an abstraction of a channel.
218 Likewise, a riece-user object provides an abstraction of a user.
219
220 **** riece-channel objects
221
222 A riece-channel object has many information about a channel.  A
223 riece-channel object is actually a vector whose seven elements are listed
224 below.
225
226 - users
227   A list of nicknames which are of users in this channel.
228
229 - operators
230   A list of nicknames which are of channel operators in this channel.
231
232 - speakers
233   A list of nicknames which are of users who have the right to speak
234   in this channel.
235
236 - modes
237   An alist which represents modes of this channel.
238
239 - banned
240   A list of patterns set by MODE +b.
241
242 - invited
243   A list of patterns set by MODE +I.
244
245 - uninvited
246   A list of patterns set by MODE +e.
247
248 **** riece-user objects
249
250 A riece-user object has many information about a user.  A riece-user
251 object is actually a vector whose four elements are listed below.
252
253 - channels
254   A list of channel names this user is participating.
255
256 - user-at-host
257   Connection information of this user, set in "<user>@<host>" format.
258
259 - modes
260   An alist which represents modes of this user.
261
262 - away
263   A flag represent whether this user is AWAY.
264
265 **** The Mediator pattern
266
267 The riece-naming module is used to manage relationships between
268 channels and users.  It utilizes the Mediator design pattern.
269
270 Using the riece-naming module allows to safely access to the namespace
271 rather than directly connects riece-channel/riece-user objects.
272
273 The riece-naming module provides the following functions.
274
275 - riece-naming-assert-join user-name channel-name
276   Assert that a user is a member of a channel.
277
278 - riece-naming-assert-part user-name channel-name
279   Assert that a user is no longer a member of a channel.
280
281 - riece-naming-assert-rename old-name new-name
282   Assert that a user changed his nickname.
283
284 ** Signals
285
286 There is a mechanism to connect events and display objects (windows,
287 buffers, and modeline indicators).  This is done by signals.
288
289 When it is needed to redraw, a signal is emitted.  The concept of
290 signals is corresponding to signals in generic window system toolkit
291 such as Qt or GTK+.
292
293 To emit a signal, use riece-emit-signal.
294
295 - riece-emit-signal signal-name &rest args
296   Emit a signal named signal-name with args.
297
298 To define a function called when a signal is emitted, use
299 riece-connect-signal.
300
301 - riece-connect-signal signal-name slot-function &optional
302                        filter-function handback
303
304   Give a signal a slot-function.  The slot-function gets two
305   arguments: the signal object itself and a handback object given as
306   the fourth argument of riece-connect-signal.
307
308   If the third argument filter-function is specified, the
309   slot-function is called conditionally.  The filter-function gets the
310   signal object and returns nil or t.  If the return value is nil, the
311   slot-function is not called.
312
313 To access to a signal object, use the following functions.
314
315 - riece-signal-name signal
316   Return the name of a signal.
317
318 - riece-signal-args
319   Return the data of a signal.
320
321 Below is a list of signal names reserved.
322
323 - channel-list-changed
324   Need update the channel list.
325
326 - user-list-changed
327   Need update the user list.
328   (This signal gets a riece-identity object as an argument which
329   represents the channel.)
330
331 - channel-switched
332   A user selected another channel.
333
334 - user-joined-channel
335   A user joined a channel.
336   (This signal gets two riece-identity objects as arguments
337   corresponding to the user and the channel respectively.)
338
339 - user-left-channel
340   A user left a channel.
341   (This signal gets two riece-identity objects as arguments
342   corresponding to the user and the channel respectively.)
343
344 - user-renamed
345   A user changed his nickname.
346   (This signal gets two riece-identity objects as arguments
347   corresponding to the old and the new nickname respectively.)
348
349 - user-away-changed
350   A user changed his AWAY status.
351   (This signal gets a riece-identity object as an argument which
352   represents the user.)
353
354 - user-operator-changed
355   A user changed his IRC operator status. 
356   (This signal gets a riece-identity object as an argument which
357   represents the user.)
358
359 - channel-topic-changed
360   A topic of a channel changed.
361   (This signal gets a riece-identity object as an argument which
362   represents the channel.)
363
364 - channel-modes-changed
365   Modes of a channel changed.
366   (This signal gets a riece-identity object as an argument which
367   represents the channel.)
368
369 - channel-operators-changed
370   A list of operators in a channel changed.
371   (This signal gets a riece-identity object as an argument which
372   represents the channel.)
373
374 - channel-speakers-changed
375   A list of users who have the right to speak in a channel changed.
376   (This signal gets a riece-identity object as an argument which
377   represents the channel.)
378
379 - buffer-freeze-changed
380   A buffer is frozen or unfrozen.
381   (This signal gets a buffer as an argument.)
382
383 ** Writing add-ons
384
385 Elisp modules that satisfy add-on spec should provide the following
386 functions.
387
388 - <module-name>-requires
389   Return a list of names of other add-ons this add-on depends. (optional)
390
391 - <module-name>-insinuate
392   Called on initialization of this module.
393
394 It is recommended to set short explanation of the add-on to
395 <module-name>-description variable which is displayed on add-on
396 listing shown up by C-c ^ (M-x riece-command-list-addons).
397
398 Add-ons that support enabling/disabling set the current status to
399 <module-name>-enabled variable.  If this variable is nil, the add-on
400 is regarded as currently disabled.  In addition, the add-on must
401 provide the following two functions.
402
403 - <module-name>-enable
404   Called to enable this add-on.
405
406 - <module-name>-disable
407   Called to disable this add-on.
408
409 Riece does the following process when startup.
410
411 (1) Load add-ons listed in the riece-addons variable.
412
413 (2) Call <module-name>-requires on each add-on (if exists) and build a
414     dependency graph.
415
416 (3) Sort the dependency graph.
417
418 (4) Call <module-name>-insinuate on each add-on in order of the
419     dependencies.
420
421 (5) Call <module-name>-enable on each add-on, iff it supports
422     enabling/disabling and is not disabled explicitly.
423
424 Add-ons are loaded from directories listed in load-path, or from
425 ~/.riece/addons/.
426
427 ** Handler hooks
428
429 There are hooks called "handler hooks " which have special meaning in
430 Riece.  Handler hooks are called before/after processing IRC messages.
431
432 - riece-<message>-hook
433   Called before processing an IRC message.
434
435 - riece-after-<message>-hook
436   Called after processing an IRC message.
437
438 Where <message> is a type of IRC message and consists only lowercase
439 characters.
440
441 If riece-<message>-hook returns non-nil, <message> is not processed.
442 In this case riece-after-<message>-hook is not called.
443
444 Handler hooks gets two arguments corresponding to prefix and
445 parameters in RFC2812.