6.3.90.900
IRC Client: High-Level IRC API
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 (conn ready-evt) (irc-connect "irc.example.com" 6667 |
| "nickname" "username" "Real Name")) |
| (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:
2 Managing IRC Connections
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.
Joins the provided IRC channel on the server connected to via connection.
Leaves the provided IRC channel on the server connected to via connection.
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.
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.
Sends the given
message to
target. Similar to
irc-send-message!, but sends
the message as an IRC
NOTICE rather than a
PRIVMSG.
Sets the nickname of the client connected via connection to nick.
Sets the username and real name of the client connected via connection to username
and real-name, respectively.
Disconnects from the IRC server. If message is provided, a custom quit reason is supplied,
otherwise the quit reason is left empty.
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.
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.
3 Structure Types
Represents a connection an IRC server. The
internal-connection field allows access to the
underlying
irc connection object, if needed for whatever reason.
Represents an IRC user, and is included in various
IrcMessage subtypes.
3.1 Message Types
The supertype for all IRC message structures. The
internal-message field allows access to the
underlying
irc message object, if needed for whatever reason.
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.
Sent when a user joins a channel the client is currently connected to.
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).
Sent when a user disconnects from the server. Also includes the provided reason for
leaving (though it may be empty).
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).
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.
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.