chickadee » irc

irc

Description

A simple IRC client library.

Author

felix winkelmann

Requirements

matchable, regex, srfi-1

Documentation

This extension provides basic support for the IRC client protocol (RFC 2812). Note that some basic knowledge of the protocol will be needed to use this library.

Error-replies from the server are signalled as composite conditions of kind (exn irc) with the properties code (the IRC error code) and reply (the actual message object received). If the connection is terminated by the server, a composite condition of the kinds (exn irc/eof) is signalled. Automatic reconnection on timeout or eof is supported and optional.

irc:connection

irc:connection #!key user password server nick real-name port log-traffic ping-timeout reconnect reconnect-timeoutprocedure

Returns a connection object, where the following keyword arguments specify the connection parameters:

keywordargument typedefault
userstringnobody
passwordstringnone
serverstringnone
nickstringsome random symbol
real-namestringsame as the user parameter
portinteger6667
log-trafficport or #f#f
reconnect-timeoutmilliseconds (integer)3600000
reconnectboolean#f

A server must be provided in any case.

The connection object can be queried using the following accessors:

irc:connection? Xprocedure

Returns #t if X is a connection object, or #f otherwise.

irc:connection-in CONNECTIONprocedure
irc:connection-out CONNECTIONprocedure
irc:connection-server CONNECTIONprocedure
irc:connection-nick CONNECTIONprocedure
irc:connection-user CONNECTIONprocedure
irc:connection-real-name CONNECTIONprocedure
irc:connection-port CONNECTIONprocedure
irc:connection-channels CONNECTIONprocedure
irc:connection-log-file CONNECTIONprocedure
irc:connection-reconnect-timeout CONNECTIONprocedure
irc:connection-password CONNECTIONprocedure
irc:connection-reconnect? CONNECTIONprocedure

Accessors for values stored in a connection object. The in and out values are ports, port is an integer, channel is a string and all other values are strings.

irc:connection-raw-filter-set!

irc:connection-raw-filter-set! CONNECTION PROCprocedure

When set, then each line of received input will first be processed by the one argument procedure PROC, and the result be passed to the message deconstruction machinery instead. Use this facility to perform very low level pre-processing of input from the IRC server.

irc:connect

irc:connect CONNECTIONprocedure
irc:connect #!key KEYWORD ...procedure

Connects to an IRC server, with the parameters given in the connection object CONNECTION or via the parameters passed as keywords arguments (just like in the call to irc:connection). Returns the connection object. A connection can only be made to a single server at the same time.

irc:disconnect

irc:disconnect CONNECTIONprocedure

Disconnects any currently active connection.

irc:reconnect

irc:reconnect CONNECTIONprocedure

Disconnect and reconnect to CONNECTION, automatically re-joining all channels that we have currently joined.

irc:connected?

irc:connected? CONNECTIONprocedure

Returns #t if there exists an open connection for CONNECTION, or #f otherwise.

irc:quit

irc:quit CONNECTION #!optional MESSAGEprocedure

Sends a QUIT message to the IRC server (optionally with the text MESSAGE) and closes the connection designated by the connection object CONNECTION.

irc:join

irc:join CONNECTION CHANNELprocedure

Sends JOIN messages for the given CHANNEL (a string).

irc:part

irc:part CONNECTION CHANNELprocedure
irc:leave CONNECTION CHANNELprocedure

Leaves the channels given in the string CHANNEL by sending a PART message.

irc:nick

irc:nick CONNECTION NICKprocedure

Changes the nickname to the one given in the string NICK.

irc:say

irc:say CONNECTION MESSAGE DESTINATION ...procedure

Sends the string MESSAGE via a PRIVMSG command to the given destinations, which should be strings designating either channels or nicknames. If no destinations are given, the message is sent to the last channel that has been joined. The message is split into multiple PRIVMSG operations, if it contains newline characters.

irc:notice

irc:notice CONNECTION MESSAGE DESTINATION ...procedure

Similar to irc:say but uses a NOTICE command instead.

irc:action

irc:action CONNECTION MESSAGE DESTINATION ...procedure

Similar to irc:say but Sends an "action" instead of a normal message.

irc:command

irc:command CONNECTION STRINGprocedure

Sends an arbitrary IRC command to the server.

irc:listen

irc:listen CONNECTIONprocedure

If data is available for reading, then the incoming message is parsed and a "message" object is returned. If no data is currently available, #f is returned.

The message object can be queried with the following procedures:

irc:message? Xprocedure

Returns #t if X is a message object, or #f otherwise.

irc:message-prefix MESSAGEprocedure
irc:message-command MESSAGEprocedure
irc:message-timestamp MESSAGEprocedure
irc:message-code MESSAGEprocedure
irc:message-body MESSAGEprocedure
irc:message-parameters MESSAGEprocedure
irc:message-index MESSAGEprocedure

Return the components of a message object. The prefix is either a list of the form (SERVERNAME) or a list containing the message prefix of the form (NICK USER HOST) (all values are strings). The timestamp holds the current number of seconds (as returned by (current-seconds)) at the point when the message was parsed. The body contains the complete message string. The code is a numerical command-code for the message or #f. The parameters is a list of strings, containing message destination and message body. If the message contains extended information (mostly ACTIONs), then the last value in the list is an extended data object. The index is a numeric message index.

irc:message-sender

irc:message-sender MESSAGEprocedure
irc:message-receiver MESSAGEprocedure

Returns the sender and receiver of a message, respectively. The receiver may be a channel name or the nickname of another client.

irc:extended-data?

irc:extended-data? Xprocedure

Returns #t if X is an extended data object, or #f otherwise.

irc:extended-data-tag

irc:extended-data-tag EXTENDEDprocedure
irc:extended-data-content EXTENDEDprocedure

Return the tag (symbol) and content (string) parts of an extended data object.

irc:wait

irc:wait CONNECTIONprocedure

Waits until data is available from CONNECTION and returns the parsed message object.

irc:process-message

irc:process-message CONNECTION MESSAGE #!optional VERBOSEprocedure

Calls any registered message handlers that apply to MESSAGE. If the optional argument VERBOSE is given and true, then diagnostic output will be written to the port returned by (current-output-port).

irc:run-message-loop

irc:run-message-loop CONNECTION #!key debug pong filterprocedure

Repeatedly calls irc:wait and irc:process-message. If the keyword argument debug is given and true, then each incoming message will be dumped to the port given by the value of (current-output-port). The keyword argument pong specifies whether automatic processing of PING messages should be done. If yes, then a message handler with the tag ping (a symbol) will be registered as with the following commands:

 (irc:add-message-handler! 
   con
   (lambda (msg)
     (irc:command con (string-append "PONG :" (car (irc:message-parameters msg)))) )
   tag: 'ping
   command: "PING") )

The keyword argument filter can be used to specify a procedure that will be called for each icoming message object (the result will be used for further processing instead).

irc:add-message-handler!

irc:add-message-handler! CONNECTION PROC #!key command sender receiver body tag codeprocedure

Defines a message handler for the given CONNECTION that will invoke the one argument procedure PROC with the received message object when all of the regular expressions given for the keyword arguments match (uses string-search), and the code, which should be an exact integer (and is compared using eq?).

The keyword tag defines a message-handler tag, which can be used to remove the handler at a later time.

Note that if this procedure is called with two arguments (and no keyword args), then the message handler will be invoked for all incoming messages.

Message handlers are run in the order in which they are defined. A message handler should return #f if further handlers should be invoked for the same message, or true if other handlers should not be called.

The command, sender, receiver and body arguments may optionally be predicates instead of strings (which will be called with the respective part of the checked message) to allow more fine-grained matching.

irc:remove-message-handler!

irc:remove-message-handler! CONNECTION TAGprocedure

Removes the message handler with the given tag.

Example

A minimalistic bot that shows the current time, when asked:

(import irc (chicken time) (chicken time posix))

(define con
  (irc:connection server: "irc.libera.chat" nick: "PongoTwistleton") )

(define (bleep _)
  (irc:say con (seconds->string (current-seconds)) "#somechannel") )

(irc:connect con)

(irc:join con "#somechannel")

(irc:add-message-handler!
 con bleep
 command: "PRIVMSG" body: "time")

(irc:run-message-loop con debug: #t)

Changelog

License

 Copyright (c) 2000-2009, Felix L. Winkelmann
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
 conditions are met:
 
   Redistributions of source code must retain the above copyright notice, this list of conditions and the following
     disclaimer. 
   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
     disclaimer in the documentation and/or other materials provided with the distribution. 
   Neither the name of the author nor the names of its contributors may be used to endorse or promote
     products derived from this software without specific prior written permission. 
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICESLOSS OF USE, DATA, OR PROFITSOR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.

Contents »