doc/HACKING

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