1 $Id: user-guide.txt 88 2005-03-20 16:55:43Z ehuelsmann $
  2 $Source$
  3 
  4 A user's guide to cl-irc.  The user is thought of as a Common Lisp
  5 programmer using the library in his own code.
  6 
  7   Introduction to IRC
  8 
  9     If you haven't already, now is probably a good time to read the
 10     relevant RFCs (distributed with this software).  You certainly
 11     don't have to but it will help your understanding of the domain.
 12     RFC2810 is a short text on the architecture of the protocols.
 13 
 14   About this library
 15 
 16     cl-irc is an implementation of the client-side protocol.
 17     It is not impossible to add the server-side but it has simple not
 18     been done yet (and the current authors have no plans of doing so,
 19     although patches are certainly welcome).
 20 
 21     Here's the basic idea: You tell the library to connect to an IRC
 22     server; it gives you a connection object in return.  You call
 23     `read-message-loop' which reads messages from the server.  For
 24     each message that is received, it is parsed and the library tries
 25     to find a hook to apply to the message (see ``Hooks'') and if
 26     successful the hook will be called with the message as its single
 27     argument.  You customize the library via the hooks.
 28 
 29   Multiple connections
 30 
 31     The library has been designed in such a way that all state is
 32     centered around the connection object.  As such, multiple,
 33     instances are perfectly feasible and there is no global state the
 34     user needs to worry about.
 35 
 36   Hooks
 37 
 38     The following operators are available to help dealing with hooks:
 39 
 40       - get-hooks
 41       - remove-hooks
 42       - add-hook
 43       - remove-hook
 44 
 45     Register your operator (must accept one argument which will be a
 46     message object) with `add-hook' and it will be called the next
 47     time the library receives a message for your connection.
 48 
 49   Modes
 50 
 51     The library tracks modes and mode changes for channels and users
 52     and sets mode fields accordingly.  To manipulate modes, use:
 53 
 54       - add-mode
 55       - remove-mode
 56       - has-mode-p
 57       - has-mode-value-p
 58       - set-mode
 59       - unset-mode
 60 
 61     on objects of class `user' or `channel'.  Note that these only change
 62     local state.  You'll need to use the `mode' method to send mode
 63     changes over the network.
 64 
 65     The library translates modes from the network (designated by
 66     characters) to keywords.  These keywords are then used as the
 67     `mode-name' argument for the above methods.  Any value can be used
 68     as a mode name when introducing custom modes.
 69 
 70     Modes which take on `on' or `off' values, like the `a' user
 71     mode (away), return `nil' for `has-mode-value-p' to signal `off' and
 72     `t' to signal `on'.
 73 
 74     Applications which want to track their own modes need to append
 75     the return value from the `make-mode-description' function to either
 76     the channel-mode-descriptions or user-mode-descriptions field.
 77 
 78   An example
 79 
 80     * (require :cl-irc)
 81 
 82     * (in-package :irc)
 83 
 84     * (setf connection (connect :nickname "mynick"
 85                                 :server "irc.somewhere.org"))
 86 
 87     * (read-message-loop connection)
 88 
 89     ^C [snip implementation signaling condition]
 90 
 91     * (join connection "#lisp")
 92 
 93     * (read-message-loop connection)
 94 
 95     After this you might wish to exit the loop again and poke at the
 96     connection object.  As mentioned, the library by default keeps
 97     your connection object current with regards to users
 98     leaving/joining channels, topics changing, etc.
 99 
100   The future
101 
102     A multiprocessing interface to the blocking calls would be nice.
103 
104   Feedback
105 
106     Please direct any feedback to cl-irc-devel@common-lisp.net