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

Last change on this file since 23079 was 23079, checked in by felix winkelmann, 10 years ago

contracts/irc updates

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