| 1 | $Id: user-guide.txt 2 2004-01-05 14:13:03Z eenge $ |
|---|
| 2 | $Source$ |
|---|
| 3 | |
|---|
| 4 | A user's guide to net-nittin-irc. The user is thought of as a Common |
|---|
| 5 | Lisp 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 | net-nittin-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 | An example |
|---|
| 50 | |
|---|
| 51 | * (require :net-nittin-irc) |
|---|
| 52 | |
|---|
| 53 | * (in-package :irc) |
|---|
| 54 | |
|---|
| 55 | * (setf connection (connect :nickname "mynick" |
|---|
| 56 | :server "irc.somewhere.org")) |
|---|
| 57 | |
|---|
| 58 | * (read-message-loop connection) |
|---|
| 59 | |
|---|
| 60 | ^C [snip implementation signaling condition] |
|---|
| 61 | |
|---|
| 62 | * (join connection "#lisp") |
|---|
| 63 | |
|---|
| 64 | * (read-message-loop connection) |
|---|
| 65 | |
|---|
| 66 | After this you might wish to exit the loop again and poke at the |
|---|
| 67 | connection object. As mentioned, the library by default keeps |
|---|
| 68 | your connection object current with regards to users |
|---|
| 69 | leaving/joining channels, topics changing, etc. |
|---|
| 70 | |
|---|
| 71 | The future |
|---|
| 72 | |
|---|
| 73 | A multiprocessing interface to the blocking calls would be nice. |
|---|
| 74 | |
|---|
| 75 | Feedback |
|---|
| 76 | |
|---|
| 77 | Please direct any feedback to net-nittin-irc-devel@common-lisp.net |
|---|
