IRC Client:   High-Level IRC API
1 Overview and Examples
2 Managing IRC Connections
irc-connect
irc-join-channel!
irc-part-channel!
irc-send-message!
irc-send-action!
irc-send-notice!
irc-set-nick!
irc-set-user-info!
irc-quit!
irc-send!
irc-recv!
irc-recv-evt
3 Structure Types
Irc  Connection
Irc  User
3.1 Message Types
Irc  Message
Irc  Message-Message
Irc  Message-Chat  Message
Irc  Message-Action  Message
Irc  Message-Notice
Irc  Message-Join
Irc  Message-Part
Irc  Message-Quit
Irc  Message-Kick
Irc  Message-Kill
Irc  Message-Nick
4 Falling Back to the Low-Level API
7.7

IRC Client: High-Level IRC API

Alexis King <lexi.lambda@gmail.com>

 (require irc-client) package: irc-client

The irc-client library is a wrapper build on top of the irc library. It provides a higher-level interface compared to irc’s comparatively low-level constructs.

It is implemented in Typed Racket and is fully compatible with typed programs, though it should work with untyped programs as well.

1 Overview and Examples

This library provides a set of constructs for interacting with IRC servers in Racket. To connect to a server, use irc-connect.

(define-values (conn ready-evt) (irc-connect "irc.example.com" 6697
                                             "nickname" "username" "Real Name"
                                             #:ssl 'auto))
(sync ready-evt)

The second value returned from irc-connect is a synchronizable event that becomes ready for synchronization once a connection to the IRC server has been established.

The first value returned is an IrcConnection object which can be used with other irc-client functions to interact with the IRC server. For example, to join an IRC channel, once would issue the following command:

(irc-join-channel! conn "#racket")

The primary difference between irc-client and irc is how recieving messages from the server works. In irc-client, the irc-recv! function returns an instance of the IrcMessage struct. This is intended to be used with match to handle various types of commands. For example, to handle chat and action messages separately, one would use the following match structure:

(let loop ()
  (match (irc-recv! conn)
    [(IrcMessage-ChatMessage _ (IrcUser nick _ _) recipient content)
     (printf "(~a) <~a> ~a\n" recipient nick content)]
    [(IrcMessage-ActionMessage _ (IrcUser nick _ _) recipient content)
     (printf "(~a) * ~a ~a\n" recipient nick content)]
    [_ (void)])
  (loop))

2 Managing IRC Connections

procedure

(irc-connect host    
  port    
  nick    
  username    
  real-name)  
IrcConnection (Evtof Semaphore)
  host : String
  port : Nonnegative-Integer
  nick : String
  username : String
  real-name : String
Establishes a connection to an IRC server at the given host on the given port. The synchronizable event returned becomes ready for synchronization once a connection to the server has been established, at which point additional client commands can be issued.

procedure

(irc-join-channel! connection channel)  Void

  connection : IrcConnection
  channel : String
Joins the provided IRC channel on the server connected to via connection.

procedure

(irc-part-channel! connection channel)  Void

  connection : IrcConnection
  channel : String
Leaves the provided IRC channel on the server connected to via connection.

procedure

(irc-send-message! connection    
  target    
  message)  Void
  connection : IrcConnection
  target : String
  message : String
Sends the given message to target, which may be an IRC channel or the nickname of a user currently connected to IRC. If target represents a channel, it should be prefixed with the usual "#" used by IRC to distinguish channels.

procedure

(irc-send-action! connection target message)  Void

  connection : IrcConnection
  target : String
  message : String
Sends the given message to target. Similar to irc-send-message!, but it sends the message formatted as a CTCP ACTION command. Most IRC clients implement this functionality via a /me command and display action messages differently from ordinary messages.

procedure

(irc-send-notice! connection target message)  Void

  connection : IrcConnection
  target : String
  message : String
Sends the given message to target. Similar to irc-send-message!, but sends the message as an IRC NOTICE rather than a PRIVMSG.

procedure

(irc-set-nick! connection nick)  Void

  connection : IrcConnection
  nick : String
Sets the nickname of the client connected via connection to nick.

procedure

(irc-set-user-info! connection    
  username    
  real-name)  Void
  connection : IrcConnection
  username : String
  real-name : String
Sets the username and real name of the client connected via connection to username and real-name, respectively.

procedure

(irc-quit! connection [message])  Void

  connection : IrcConnection
  message : String = ""
Disconnects from the IRC server. If message is provided, a custom quit reason is supplied, otherwise the quit reason is left empty.

procedure

(irc-send! connection command args ...)  Void

  connection : IrcConnection
  command : String
  args : String
Sends a raw command to the IRC server. Use this function if you need to send something to the server not supported by any of the higher-level commands.

procedure

(irc-recv! connection)  IrcMessage

  connection : IrcConnection
Recieves a message from the IRC server as an instance of IrcMessage. Messages are internally queued, so if a message is available, it will be returned immediately. Otherwise, this function will block until a message arrives.

If the connection is closed, an exn:fail will be raised.

procedure

(irc-recv-evt connection)  (Evtof IrcMessage)

  connection : IrcConnection
Returns a synchronizable event that waits for an incoming message from the connection. The synchronization result is the IrcMessage recieved.

If the connection is closed, an exn:fail will be raised.

3 Structure Types

struct

(struct IrcConnection (internal-connection)
    #:transparent)
  internal-connection : irc:irc-connection?
Represents a connection an IRC server. The internal-connection field allows access to the underlying irc connection object, if needed for whatever reason.

struct

(struct IrcUser (nick username host)
    #:transparent)
  nick : String
  username : String
  host : String
Represents an IRC user, and is included in various IrcMessage subtypes.

3.1 Message Types

struct

(struct IrcMessage (internal-message)
    #:transparent)
  internal-message : irc:irc-message?
The supertype for all IRC message structures. The internal-message field allows access to the underlying irc message object, if needed for whatever reason.

struct

(struct IrcMessage-Message IrcMessage (sender recipient content)
    #:transparent)
  sender : IrcUser
  recipient : String
  content : String
Represents an ordinary message sent from the IRC server from the given sender to the given recipient, which may be a nickname (the client’s nickname, in which case it is a private message) or a channel.

This type is used for all kinds of PRIVMSG commands sent from the server, which includes CTCP ACTIONs. However, CTCP actions will be parsed, so content will not include the extra CTCP formatting. Since it it useful to distinguish between the two types of messages, the IrcMessage-ChatMessage and IrcMessage-ActionMessage subtypes are provided.

Note that IrcMessage-Notice is not a subtype of IrcMessage-Message—it is an independent structure type.

struct

(struct IrcMessage-ChatMessage IrcMessage-Message ()
    #:transparent)

struct

(struct IrcMessage-ActionMessage IrcMessage-Message ()
    #:transparent)
Subtypes of IrcMessage-Message used to distinguish between normal chat messages and CTCP ACTIONs. See IrcMessage-Message for more information.

struct

(struct IrcMessage-Notice IrcMessage (sender recipient content)
    #:transparent)
  sender : IrcUser
  recipient : String
  content : String
Similar to IrcMessage-Message but for NOTICE commands rather than PRIVMSG commands.

struct

(struct IrcMessage-Join IrcMessage (user channel)
    #:transparent)
  user : IrcUser
  channel : String
Sent when a user joins a channel the client is currently connected to.

struct

(struct IrcMessage-Part IrcMessage (user channel reason)
    #:transparent)
  user : IrcUser
  channel : String
  reason : String
Sent when a user leaves a channel the client is currently connected to. Also includes the provided reason for leaving the channel (though it may be empty).

struct

(struct IrcMessage-Quit IrcMessage (user reason)
    #:transparent)
  user : IrcUser
  reason : String
Sent when a user disconnects from the server. Also includes the provided reason for leaving (though it may be empty).

struct

(struct IrcMessage-Kick IrcMessage (user
    channel
    kicked-user
    reason)
    #:transparent)
  user : IrcUser
  channel : String
  kicked-user : String
  reason : String
Sent when a the user with kicked-user as a nickname is kicked from a channel by user. Also includes the provided reason the user was kicked (though it may be empty).

struct

(struct IrcMessage-Kill IrcMessage (user killed-user reason)
    #:transparent)
  user : IrcUser
  killed-user : String
  reason : String
Sent when a the user with kicked-user as a nickname is forcibly disconnected from the server by user. Also includes the provided reason the user was killed.

struct

(struct IrcMessage-Nick IrcMessage (user new-nick)
    #:transparent)
  user : IrcUser
  new-nick : String
Sent when a user’s nickname is changed to new-nick.

4 Falling Back to the Low-Level API

The irc-client library does provide tools for interacting with the lower-level irc API if necessary. The underlying irc:irc-connection? instance is accessible via the IrcConnection-internal-connection field, and every instance of IrcMessage includes the IrcMessage-internal-message field for retrieving the irc:irc-message instance.