IRC Client Library

6.3.90.900

top ← prev up next →

IRC Client Library

package: irc

The irc library allows you to develop IRC clients and communicate over IRC.

1 Quick Start

To use the IRC client library, first create a connection with irc-connect. For example, to connect to the Freenode (chat.freenode.net, port 6667) with nickname "rackbot", username "rbot", and real name "Racket Bot", do

(define-values (connection ready)
(irc-connect "chat.freenode.net" 6667 "rackbot" "rbot" "Racket Bot"))

This defines an irc-connection object which must be used for all future communication with this server, as well as an event that will be ready for synchronization when the server is ready to accept more commands (i.e. when the connection has been fully established).

Once the returned event fires, you can use other IRC commands. For example, if you have a connection object named connection, you can join the #racket channel with

(irc-join-channel connection "#racket")

Once you have joined, you can send a message on that channel with the following:

(irc-send-message connection "#racket" "Hello, world!")

2 Data Structures

struct
(struct irc-message (prefix command parameters content))
  prefix : (or/c string? #f)
  command : string?
  parameters : (listof string?)
  content : string?

Represents an IRC message, parsed into the prefix, command, and parameters. If the message did not contain a prefix, prefix is #f. The original raw message line is available in the content field.

3 Procedures

procedure
(irc-connection? object) → boolean?
object : any

Returns true if the given object is an IRC connection; false otherwise.

procedure
(irc-connect server
port
nick
username
real-name
[ #:return-eof return-eof]) →
irc-connection? evt?
  server : string?
   port :
(and/c exact-nonnegative-integer?
       (integer-in 1 65535))
  nick : string?
  username : string?
  real-name : string?
  return-eof : boolean? = #f

Connects to server on port using nick as the IRC nickname, username as the username, and real-name as the user’s real name. Returns a connection object and an event that will be ready for synchronization when the server is ready to accept more commands. If return-eof is #t, the incoming stream will include an end-of-file whenever the underlying TCP stream receives one (e.g. if the connection fails).

procedure
(irc-connection-incoming connection) → async-channel?
connection : irc-connection?

Returns the channel for incoming messages on the given connection. All responses from the server are sent to this channel, and will be an irc-message or one of its subtypes, or eof if the server closes the connection and the return-eof option was used when establishing the connection.

procedure
(irc-join-channel connection channel) → void?
connection : irc-connection?
channel : string?

Joins the IRC channel channel.

procedure
(irc-part-channel connection channel) → void?
connection : irc-connection?
channel : string?

Parts from (leaves) the IRC channel channel.

procedure
(irc-send-message connection target message) → void?
  connection : irc-connection?
  target : string?
  message : string?

Sends message to target. target should be either a channel name or an IRC nick.

procedure
(irc-send-notice connection target notice) → void?
  connection : irc-connection?
  target : string?
  notice : string?

Sends the notice notice to target. target should be either a channel name or an IRC nick.

procedure
(irc-get-connection host
port
[ #:return-eof return-eof]) → irc-connection?
  host : string?
   port :
(and/c exact-nonnegative-integer?
(integer-in 1 65535))
  return-eof : boolean? = #f

Establishes a connection to the IRC server host on the given port. When return-eof is #t, eof will be returned over the incoming channel when the server closes the connection.

Use this form instead of irc-connect when you want more control over when to send the NICK and USER commands.

procedure
(irc-set-nick connection nick) → void?
connection : irc-connection?
nick : string?

Sets the nickname for this connection to nick. Note that irc-connect runs this command for you when the connection is first established.

procedure
(irc-set-user-info connection
username
real-name) → void?
  connection : irc-connection?
  username : string?
  real-name : string?

Sets the user name and real name for this connection to username and real-name, respectively . Note that irc-connect runs this command for you when the connection is first established.

procedure
(irc-quit connection [quit-message]) → void?
connection : irc-connection?
quit-message : string? = ""

Quits the IRC session with an optional quit-message and closes the connection.

procedure
(irc-send-command connection
command
args ...) → void?
  connection : irc-connection?
  command : string?
  args : string?

Sends the given IRC command ands its args over the given connection. This is the most general method for sending commands to IRC, but the other functions described above should be preferred where applicable.

4 Further Information

For more information on the IRC client protocol, see RFC 2812.

top ← prev up next →