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