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