Updates/improvements -- riece-xfaceb

[riece] / README-hacking

-*- mode: outline -*-

This document is for Riece developers or those who are interested in
the development.

* Development process

** Reporting bugs

If you find a bug, please file it at
https://savannah.nongnu.org/bugs/?group=riece

** Getting the development source code

We currently use Git.  Follow the instructions below to build the
development version.

(1) checkout modules

    git clone git://git.sv.gnu.org/riece.git

(2) generate configure script

    ./bootstrap

(3) run the configure script

    ./configure

(4) build and install

    make
    make install

* Source structure

** Modules

Riece consists of many elisp modules listed below, ordered by the
number of dependencies they have.

- riece-globals
  This module defines global variables.

- riece-options
  This module defines user options.

- riece-version
  This module defines the version of Riece.

- riece-coding
  This module provides functions which support character code conversions.

- riece-complete
  This module provides functions which support tab completion feature
  in a mini buffer.

- riece-addon
  This module manages add-ons.

- riece-mode
  This module manages modes of riece-channel/riece-user objects.

- riece-identity
  This module defines the riece-identity object type which represents
  global names of riece-channel/riece-user objects.

- riece-channel
  This module defines the riece-channel object type.

- riece-user
  This module defines the riece-user object type.

- riece-misc
  This module provides miscellaneous functions.

- riece-signal
  This module defines the riece-signal object type used to manage
  display events.

- riece-layout
  This module manages window layouts.

- riece-display
  This module manages display events.

- riece-server
  This module manages connections to IRC servers.

- riece-naming
  This module is a so called the Mediator design pattern.  It knows
  relationships of riece-channel/riece-user objects.

- riece-message
  This module defines the riece-message object type.

- riece-filter
  This module only provides the process filter function.

- riece-handle
  This module provides handler functions for IRC messages.  These
  functions are called from riece-filter.

- riece-000
  This module provides handler functions for numeric replies whose
  response codes are in 000 to 100 range.  These handlers are called
  from riece-filter.

- riece-200
  This module provides handler functions for numeric replies whose
  response codes are in 200 to 300 range.  These handlers are called
  from riece-filter.

- riece-300
  This module provides handler functions for numeric replies whose
  response codes are in 300 to 400 range.  These handlers are called
  from riece-filter.

- riece-400
  This module provides handler functions for numeric replies whose
  response codes are in 400 to 500 range.  These handlers are called
  from riece-filter.

- riece-500
  This module provides handler functions for numeric replies whose
  response codes are in 500 to 600 range.  These handlers are called
  from riece-filter.

- riece-commands
  This module provides user commands.

- riece-irc
  This module provides the binding for the IRC protocol.

- riece
  This module is the entry point of M-x riece.

** Namespace management

Riece is capable to connect to several IRC servers.

Riece has separate namespace (obarray) for each connection.  These
namespaces can be accessed as buffer local variables of process
buffer.

*** Obtaining server buffer

To access to the buffer local variables of process buffer, it is
needed to distinguish process object of each connection by its name.

It can be known by:

(1) checking the value of riece-overriding-server-name,

(2) checking the value of riece-server-name,
    (If the variable riece-server-name is local to the current buffer,
    you are already in the process buffer.)

(3) or parsing riece-identity objects

Once you get the name of the IRC server, you can get the process
object by passing the name to the function riece-server-process.

*** riece-identity objects

A riece-identity object represents a name of a channel/user.  It is
used to distinguish a channel/user among several servers.

A riece-identity object is actually a vector, which consists of two
elements listed below.

- prefix
  A channel/user name local to an IRC server.

- server
  The name of the IRC server.

Methods to manipulate riece-identity object are listed below.

- riece-make-identity prefix &optional server
  Create a new riece-identity object.  If the server argument is
  omitted, it sets the server part to the value returned by the
  riece-find-server-name function.

- riece-identity-prefix identity
  Return the prefix element from the given riece-identity object.

- riece-identity-server identity
  Return the server element from the given riece-identity object.

- riece-identity-equal ident1 ident2
  Return t, if two riece-identity objects are equal.

- riece-identity-equal-no-server ident1 ident2
  Return t, if two riece-identity objects are equal.  This function
  only consider a prefix part of a riece-identity object.

- riece-identity-member elt list
  Return non-nil if a riece-identity object is an element of a list.

*** Channels and users

A riece-channel object provides an abstraction of a channel.
Likewise, a riece-user object provides an abstraction of a user.

**** riece-channel objects

A riece-channel object has many information about a channel.  A
riece-channel object is actually a vector whose seven elements are listed
below.

- users
  A list of nicknames which are of users in this channel.

- operators
  A list of nicknames which are of channel operators in this channel.

- speakers
  A list of nicknames which are of users who have the right to speak
  in this channel.

- modes
  An alist which represents modes of this channel.

- banned
  A list of patterns set by MODE +b.

- invited
  A list of patterns set by MODE +I.

- uninvited
  A list of patterns set by MODE +e.

**** riece-user objects

A riece-user object has many information about a user.  A riece-user
object is actually a vector whose four elements are listed below.

- channels
  A list of channel names this user is participating.

- user-at-host
  Connection information of this user, set in "<user>@<host>" format.

- modes
  An alist which represents modes of this user.

- away
  A flag represent whether this user is AWAY.

**** The Mediator pattern

The riece-naming module is used to manage relationships between
channels and users.  It utilizes the Mediator design pattern.

Using the riece-naming module allows to safely access to the namespace
rather than directly connects riece-channel/riece-user objects.

The riece-naming module provides the following functions.

- riece-naming-assert-join user-name channel-name
  Assert that a user is a member of a channel.

- riece-naming-assert-part user-name channel-name
  Assert that a user is no longer a member of a channel.

- riece-naming-assert-rename old-name new-name
  Assert that a user changed his nickname.

** Signals

There is a mechanism to connect events and display objects (windows,
buffers, and modeline indicators).  This is done by signals.

When it is needed to redraw, a signal is emitted.  The concept of
signals is corresponding to signals in generic window system toolkit
such as Qt or GTK+.

To emit a signal, use riece-emit-signal.

- riece-emit-signal signal-name &rest args
  Emit a signal named signal-name with args.

To define a function called when a signal is emitted, use
riece-connect-signal.

- riece-connect-signal signal-name slot-function &optional
                       filter-function handback

  Give a signal a slot-function.  The slot-function gets two
  arguments: the signal object itself and a handback object given as
  the fourth argument of riece-connect-signal.

  If the third argument filter-function is specified, the
  slot-function is called conditionally.  The filter-function gets the
  signal object and returns nil or t.  If the return value is nil, the
  slot-function is not called.

To access to a signal object, use the following functions.

- riece-signal-name signal
  Return the name of a signal.

- riece-signal-args
  Return the data of a signal.

Below is a list of signal names reserved.

- channel-list-changed
  Need update the channel list.

- user-list-changed
  Need update the user list.
  (This signal gets a riece-identity object as an argument which
  represents the channel.)

- channel-switched
  A user selected another channel.

- user-joined-channel
  A user joined a channel.
  (This signal gets two riece-identity objects as arguments
  corresponding to the user and the channel respectively.)

- user-left-channel
  A user left a channel.
  (This signal gets two riece-identity objects as arguments
  corresponding to the user and the channel respectively.)

- user-renamed
  A user changed his nickname.
  (This signal gets two riece-identity objects as arguments
  corresponding to the old and the new nickname respectively.)

- user-away-changed
  A user changed his AWAY status.
  (This signal gets a riece-identity object as an argument which
  represents the user.)

- user-operator-changed
  A user changed his IRC operator status. 
  (This signal gets a riece-identity object as an argument which
  represents the user.)

- channel-topic-changed
  A topic of a channel changed.
  (This signal gets a riece-identity object as an argument which
  represents the channel.)

- channel-modes-changed
  Modes of a channel changed.
  (This signal gets a riece-identity object as an argument which
  represents the channel.)

- channel-operators-changed
  A list of operators in a channel changed.
  (This signal gets a riece-identity object as an argument which
  represents the channel.)

- channel-speakers-changed
  A list of users who have the right to speak in a channel changed.
  (This signal gets a riece-identity object as an argument which
  represents the channel.)

- buffer-freeze-changed
  A buffer is frozen or unfrozen.
  (This signal gets a buffer as an argument.)

** Writing add-ons

Elisp modules that satisfy add-on spec should provide the following
functions.

- <module-name>-requires (optional)
  Return a list of names of other add-ons this add-on depends.

- <module-name>-insinuate
  Called on initialization of this module.

- <module-name>-uninstall (optional)
  Called on uninstallation of this module.

- <module-name>-enable (optional)
  Called when this add-on is enabled.

- <module-name>-disable (optional)
  Called when this add-on is disabled.

It is recommended to set short explanation of the add-on to
<module-name>-description variable which is displayed on add-on
listing shown up by C-c ^ (M-x riece-command-list-addons).

To see the add-on's enabled/disabled status, check riece-addon-enabled
property set on <module-name> symbol.

Riece does the following procedure on add-ons when startup.

(1) Load add-ons listed in the riece-addons variable.

(2) Call <module-name>-requires on each add-on (if exists) and build a
    dependency graph.

(3) Sort the dependency graph.

(4) Call <module-name>-insinuate on each add-on in order of the
    dependencies.

(5) Call <module-name>-enable on each add-on, iff it supports
    enabling/disabling and is not disabled explicitly.

Add-ons are loaded from directories listed in load-path, or from
~/.riece/addons/.

** Handler hooks

There are hooks called "handler hooks " which have special meaning in
Riece.  Handler hooks are called before/after processing IRC messages.

- riece-<message>-hook
  Called before processing an IRC message.

- riece-after-<message>-hook
  Called after processing an IRC message.

Where <message> is a type of IRC message and consists only lowercase
characters.

If riece-<message>-hook returns non-nil, <message> is not processed.
In this case riece-after-<message>-hook is not called.

Handler hooks gets two arguments corresponding to prefix and
parameters in RFC2812.