IRC Client Library
1 Quick Start
2 Data Structures
irc-message
3 Procedures
irc-connection?
irc-connect
irc-connection-incoming
irc-join-channel
irc-part-channel
irc-send-message
irc-send-notice
irc-get-connection
irc-set-nick
irc-set-user-info
irc-quit
irc-send-command
4 CTCP
ctcp-action
5 Further Information
7.1

IRC Client Library

 (require irc) 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    
  #:ssl ssl])  
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
  ssl : (or/c ssl-client-context? 'auto 'sslv2-or-v3 'sslv2 'sslv3 'tls 'tls11 'tls12 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). If ssl is not #f the connection will be made over SSL/TLS with the appropriate SSL/TLS mode or client context.

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    
  #:ssl ssl])  irc-connection?
  host : string?
  port : 
(and/c exact-nonnegative-integer?
(integer-in 1 65535))
  return-eof : boolean? = #f
  ssl : (or/c ssl-client-context? 'auto 'sslv2-or-v3 'sslv2 'sslv3 'tls 'tls11 'tls12 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. If ssl is not #f the connection will be made over SSL/TLS with the appropriate SSL/TLS mode or client context.

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 CTCP

CTCP is an embeded protocol within IRC that allows for actions such as /me commands. This package currently has basic support for CTCP.

procedure

(ctcp-action connection target action)  void?

  connection : irc-connection?
  target : string?
  action : string?
Sends the given action to the target, usually displayed in the channel as "<sender-nick> <action>" (i.e. the expected result of a /me command). target should be either a channel name or an IRC nick.

5 Further Information

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