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