source: project/wiki/eggref/4/irc @ 29491

Last change on this file since 29491 was 29491, checked in by svnwiki, 7 years ago

Anonymous wiki edit for IP [76.126.226.123]: Added requirements.

File size: 12.9 KB
Line 
1[[tags: egg]]
2
3== irc
4
5[[toc:]]
6
7=== Description
8
9A simple IRC client library.
10
11=== Author
12
13[[/users/felix winkelmann|felix winkelmann]]
14
15=== Requirements
16
17[[/eggref/4/matchable|matchable]], [[/eggref/4/regex|regex]]
18
19
20=== Documentation
21
22This extension provides basic support for the IRC client protocol
23([[http://www.faqs.org/rfcs/rfc2812.html|RFC 2812]]). Note that some
24basic knowledge of the protocol will be needed to use this library.
25
26Error-replies from the server are signalled as composite conditions of
27kind {{(exn irc)}} with the properties {{code}} (the IRC error code)
28and {{reply}} (the actual message object received). If the connection
29is terminated by the server, a composite condition of the kinds
30{{(exn irc/eof)}} is signalled. Automatic reconnection on timeout or
31eof is supported and optional.
32
33==== irc:connection
34
35<procedure>(irc:connection #!key user password server nick real-name port log-traffic ping-timeout reconnect reconnect-timeout)</procedure>
36
37Returns a ''connection'' object, where the following keyword arguments
38specify the connection parameters:
39
40<table>
41<tr><th>keyword</th><th>argument type</th><th>default</th></tr>
42<tr><td>{{user}}</td><td>string</td><td>{{nobody}}</td></tr>
43<tr><td>{{password}}</td><td>string</td><td>''none''</td></tr>
44<tr><td>{{server}}</td><td>string</td><td>''none''</td></tr>
45<tr><td>{{nick}}</td><td>string</td><td>some random symbol</td></tr>
46<tr><td>{{real-name}}</td><td>string</td><td>same as the {{user}} parameter</td></tr>
47<tr><td>{{port}}</td><td>integer</td><td>6667</td></tr>
48<tr><td>{{log-traffic}}</td><td>port or #f</td><td>#f</td></tr>
49<tr><td>{{reconnect-timeout}}</td><td>milliseconds (integer)</td><td>3600000</td></tr>
50<tr><td>{{reconnect}}</td><td>boolean</td><td>#f</td></tr>
51</table>
52
53A server must be provided in any case.
54
55The connection object can be queried using the following accessors:
56
57<procedure>(irc:connection? X)</procedure>
58
59Returns {{#t}} if {{X}} is a connection object, or {{#f}} otherwise.
60
61<procedure>(irc:connection-in CONNECTION)</procedure>
62<procedure>(irc:connection-out CONNECTION)</procedure>
63<procedure>(irc:connection-server CONNECTION)</procedure>
64<procedure>(irc:connection-nick CONNECTION)</procedure>
65<procedure>(irc:connection-user CONNECTION)</procedure>
66<procedure>(irc:connection-real-name CONNECTION)</procedure>
67<procedure>(irc:connection-port CONNECTION)</procedure>
68<procedure>(irc:connection-channels CONNECTION)</procedure>
69<procedure>(irc:connection-log-file CONNECTION)</procedure>
70<procedure>(irc:connection-reconnect-timeout CONNECTION)</procedure>
71<procedure>(irc:connection-password CONNECTION)</procedure>
72<procedure>(irc:connection-reconnect? CONNECTION)</procedure>
73
74Accessors for values stored in a connection object. The {{in}} and
75{{out}} values are ports, {{port}} is an integer, {{channel}} is a
76string and all other values are strings.
77
78==== irc:connection-raw-filter-set!
79
80<procedure>(irc:connection-raw-filter-set! CONNECTION PROC)</procedure>
81
82When set, then each line of received input will first be processed by
83the one argument procedure {{PROC}}, and the result be passed to the
84message deconstruction machinery instead. Use this facility to perform
85very low level pre-processing of input from the IRC server.
86
87==== irc:connect
88
89<procedure>(irc:connect CONNECTION)</procedure>
90<procedure>(irc:connect #!key KEYWORD ...)</procedure>
91
92Connects to an IRC server, with the parameters given in the connection
93object {{CONNECTION}} or via the parameters passed as keywords
94arguments (just like in the call to {{irc:connection}}).  Returns the
95connection object. A connection can only be made to a single server at
96the same time.
97
98==== irc:disconnect
99
100<procedure>(irc:disconnect CONNECTION)</procedure>
101
102Disconnects any currently active connection.
103
104==== irc:reconnect
105
106<procedure>(irc:reconnect CONNECTION)</procedure>
107
108Disconnect and reconnect to {{CONNECTION}}, automatically re-joining
109all channels that we have currently joined.
110
111==== irc:connected?
112
113<procedure>(irc:connected? CONNECTION)</procedure>
114
115Returns {{#t}} if there exists an open connection for {{CONNECTION}},
116or {{#f}} otherwise.
117
118==== irc:quit
119
120<procedure>(irc:quit CONNECTION [MESSAGE])</procedure>
121
122Sends a {{QUIT}} message to the IRC server (optionally with the text
123{{MESSAGE}}) and closes the connection designated by the connection
124object {{CONNECTION}}.
125
126==== irc:join
127
128<procedure>(irc:join CONNECTION CHANNEL)</procedure>
129
130Sends {{JOIN}} messages for the given {{CHANNEL}} (a string).
131
132==== irc:part
133
134<procedure>(irc:part CONNECTION CHANNEL)</procedure>
135<procedure>(irc:leave CONNECTION CHANNEL)</procedure>
136
137Leaves the channels given in the string {{CHANNEL}} by sending a
138{{PART}} message.
139
140==== irc:nick
141
142<procedure>(irc:nick CONNECTION NICK)</procedure>
143
144Changes the nickname to the one given in the string {{NICK}}.
145
146==== irc:say
147
148<procedure>(irc:say CONNECTION MESSAGE DESTINATION ...)</procedure>
149
150Sends the string {{MESSAGE}} via a {{PRIVMSG}} command to the given
151destinations, which should be strings designating either channels or
152nicknames. If no destinations are given, the message is sent to the
153last channel that has been joined. The message is split into multiple
154{{PRIVMSG}} operations, if it contains newline characters.
155
156==== irc:notice
157
158<procedure>(irc:notice CONNECTION MESSAGE DESTINATION ...)</procedure>
159
160Similar to {{irc:say}} but uses a {{NOTICE}} command instead.
161
162==== irc:action
163
164<procedure>(irc:action CONNECTION MESSAGE DESTINATION ...)</procedure>
165
166Similar to {{irc:say}} but Sends an "action" instead of a normal message.
167
168==== irc:command
169
170<procedure>(irc:command CONNECTION STRING)</procedure>
171
172Sends an arbitrary IRC command to the server.
173
174==== irc:listen
175
176<procedure>(irc:listen CONNECTION)</procedure>
177
178If data is available for reading, then the incoming message is parsed
179and a "message" object is returned.  If no data is currently
180available, {{#f}} is returned.
181
182The message object can be queried with the following procedures:
183
184<procedure>(irc:message? X)</procedure>
185
186Returns {{#t}} if {{X}} is a message object, or {{#f}} otherwise.
187
188<procedure>(irc:message-prefix MESSAGE)</procedure>
189<procedure>(irc:message-command MESSAGE)</procedure>
190<procedure>(irc:message-timestamp MESSAGE)</procedure>
191<procedure>(irc:message-code MESSAGE)</procedure>
192<procedure>(irc:message-body MESSAGE)</procedure>
193<procedure>(irc:message-parameters MESSAGE)</procedure>
194<procedure>(irc:message-index MESSAGE)</procedure>
195
196Return the components of a message object. The prefix is either a list
197of the form {{(SERVERNAME)}} or a list containing the message prefix
198of the form {{(NICK USER HOST)}} (all values are strings).  The
199timestamp holds the current number of seconds (as returned by
200{{(current-seconds)}}) at the point when the message was parsed. The
201body contains the complete message string. The code is a numerical
202command-code for the message or {{#f}}. The parameters is a list of
203strings, containing message destination and message body.  If the
204message contains extended information (mostly {{ACTION}}s), then the
205last value in the list is an ''extended data'' object.  The index is a
206numeric message index.
207
208==== irc:message-sender
209
210<procedure>(irc:message-sender MESSAGE)</procedure>
211<procedure>(irc:message-receiver MESSAGE)</procedure>
212
213Returns the sender and receiver of a message, respectively. The
214receiver may be a channel name or the nickname of another client.
215
216==== irc:extended-data?
217
218<procedure>(irc:extended-data? X)</procedure>
219
220Returns {{#t}} if {{X}} is an extended data object, or {{#f}}
221otherwise.
222
223==== irc:extended-data-tag
224
225<procedure>(irc:extended-data-tag EXTENDED)</procedure>
226<procedure>(irc:extended-data-content EXTENDED)</procedure>
227
228Return the tag (symbol) and content (string) parts of an extended data
229object.
230
231==== irc:wait
232
233<procedure>(irc:wait CONNECTION)</procedure>
234
235Waits until data is available from {{CONNECTION}} and returns the
236parsed message object.
237
238==== irc:process-message
239
240<procedure>(irc:process-message CONNECTION MESSAGE [VERBOSE])</procedure>
241
242Calls any registered message handlers that apply to {{MESSAGE}}. If
243the optional argument {{VERBOSE}} is given and true, then diagnostic
244output will be written to the port returned by
245{{(current-output-port)}}.
246
247==== irc:run-message-loop
248
249<procedure>(irc:run-message-loop CONNECTION #!key debug pong filter)</procedure>
250
251Repeatedly calls {{irc:wait}} and {{irc:process-message}}. If the
252keyword argument {{debug}} is given and true, then each incoming
253message will be dumped to the port given by the value of
254{{(current-output-port)}}. The keyword argument {{pong}} specifies
255whether automatic processing of {{PING}} messages should be done. If
256yes, then a message handler with the tag {{ping}} (a symbol) will be
257registered as with the following commands:
258
259  (irc:add-message-handler!
260    con
261    (lambda (msg)
262      (irc:command con (string-append "PONG :" (car (irc:message-parameters msg)))) )
263    tag: 'ping
264    command: "PING") )
265
266The keyword argument {{filter}} can be used to specify a procedure
267that will be called for each icoming message object (the result will
268be used for further processing instead).
269
270==== irc:add-message-handler!
271
272<procedure>(irc:add-message-handler! CONNECTION PROC #!key command sender receiver body tag code)</procedure>
273
274Defines a message handler for the given {{CONNECTION}} that will
275invoke the one argument procedure {{PROC}} with the received message
276object when all of the regular expressions given for the keyword
277arguments match (uses {{string-search}}), and the
278{{code}}, which should be an exact integer (and is compared using
279{{eq?}}).
280
281The keyword {{tag}} defines a message-handler ''tag'', which can be
282used to remove the handler at a later time.
283
284Note that if this procedure is called with two arguments (and no
285keyword args), then the message handler will be invoked for all
286incoming messages.
287
288Message handlers are run in the order in which they are defined. A
289message handler should return {{#f}} if further handlers should be
290invoked for the same message, or true if other handlers should not be
291called.
292
293The {{command, sender, receiver}} and {{body}} arguments may
294optionally be predicates instead of strings (which will be called with
295the respective part of the checked message) to allow more fine-grained
296matching.
297
298==== irc:remove-message-handler!
299
300<procedure>(irc:remove-message-handler! CONNECTION TAG)</procedure>
301
302Removes the message handler with the given tag.
303
304=== Example
305
306A minimalistic bot that shows the current time, when asked:
307
308<enscript highlight="scheme">
309(require-extension irc posix)
310
311(define con
312  (irc:connection server: "irc.freenode.net" nick: "PongoTwistleton") )
313
314(define (bleep _)
315  (irc:say con (seconds->string (current-seconds)) "#somechannel") )
316
317(irc:connect con)
318
319(irc:join con "#somechannel")
320
321(irc:add-message-handler!
322 con bleep
323 command: "PRIVMSG" body: "time")
324
325(irc:run-message-loop con debug: #t)
326</enscript>
327
328=== Changelog
329
330* 1.9.3 reconnecting on timeout
331* 1.9.2 reconnect feature
332* 1.9.1 handling of server-EOF
333* 1.9 added logging and ping-timeout support
334* 1.8 uses {{string-search}} for matching handlers; allows regexp objects
335* 1.7 Ported to CHICKEN 4
336* 1.6 Added {{irc:disconnect}}
337* 1.5 Multimessage-support [Thanks to Andreas Scholta, again]
338* 1.4 Fixed bug in {{irc:remove-message-handler!}} [Thanks to Andreas Scholta]
339* 1.3 {{irc:join}} accepts only a single channel
340* 1.2 Fixed a bug in processing of handler tags [Thanks to Vesa, again!]
341* 1.1 Added {{irc:connection-raw-handler-set!}} and further options to {{irc:run-message-loop}} (in addition to {{PING}} handling) [Thanks to Vesa Kaihlavirta]
342* 1.0
343
344
345=== License
346
347  Copyright (c) 2000-2009, Felix L. Winkelmann
348  All rights reserved.
349 
350  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
351  conditions are met:
352 
353    Redistributions of source code must retain the above copyright notice, this list of conditions and the following
354      disclaimer.
355    Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
356      disclaimer in the documentation and/or other materials provided with the distribution.
357    Neither the name of the author nor the names of its contributors may be used to endorse or promote
358      products derived from this software without specific prior written permission.
359 
360  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
361  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
362  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
363  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
364  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
365  SERVICESLOSS OF USE, DATA, OR PROFITSOR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
366  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
367  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
368  POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.