Common Lisp Package: TRIVIAL-IRC

Trivial IRC client library. See `examples/echobot/' in the distribution directory for a simple example of how to use it. Currently, the exposed API is a very thin abstraction of the IRC protocol, and you probably need the IRC RFC to make use of it. The current version was slapped together in a few hours, to fill a specific need I had. It's not certain that it will evolve with much, but I'm open to suggestions and requests. If you have a better fit for trivial-irc and want to claim the name, just let me know and I'll retire this.

README:

FUNCTION

Public

PARSE-PREFIX (PREFIX)

Return a list of the components in prefix. It is a list on the form ( /server-or-nickname/ /username/ /host/) where - /servername-or-nickname/ is a servername or a nickname, - /username/ is a username, or `nil' - /host/ is a hostname, or `nil' This can potentially be used to build other abstractions later.

PREFIX-NICKNAME (PREFIX)

Return the nickname in extracted from /prefix/.

PREFIX-SERVERNAME (PREFIX)

Return the servername extracted from /prefix/.

SEND-RAW-MESSAGE (CLIENT RAW-MESSAGE)

Send /raw-message/ and CRLF to the socket associated with /client/. Outside of the few send-* functions, this is what you have to use to send messages to the server.

Private

.NICK (CLIENT)

Send /client/'s nickname to server. Called by `connect' during registration.

.PASSWORD (CLIENT)

Send /client/'s password if a password is associated with /client/.

.USER (CLIENT)

Send /client/'s username and realname to server. Called by `connect' during registration.

PARSE-RAW-MESSAGE (RAW-MESSAGE)

Return a list on the form (prefix command arguments). /prefix/ can be `nil', or servername / ( nickname [ [ "!" user ] "@" host ] See also the `parse-prefix' function. /command/ is a keyword either made from the alpha-characters, or a keyword looked up with `find-reply-name'. /arguments/ is a list of the command arguments.

RECEIVE-RAW-MESSAGE (CLIENT)

Receive and return a single, raw message from /client/. If any errors occur during the reading, the connection is silently shut down.

SERVERNAME-OR-NICKNAME (PREFIX)

Return the servername or nickname from /prefix-string/.

Undocumented

.QUIT (CLIENT &OPTIONAL (MESSAGE *DEFAULT-QUIT-MESSAGE*))

FIND-REPLY-NAME (REPLY-NUMBER)

PARSE-ARGUMENT-STRING (ARGUMENT-STRING)

RECORD (CLIENT STRING)

UNIVERSAL-TIME->ISO-8601-STRING (UNIVERSAL-TIME &KEY (DETAIL SECOND))

MACRO

Public

DEFINE-HANDLER ((COMMAND CLASS-SPEC PREFIX-VAR ARGUMENTS-VAR) &BODY BODY)

Define handling for /command/. This is currently a convenience for specializing on `handle'. An example is the handler for PING messages (which by default is the only handler specialization). -- ;; (define-handler (:ping client prefix arguments) ;; (send-pong client (first arguments))) -- If you wanted to use a different variable-name for the client variable, you could also have written it as -- ;; (define-handler (:ping (client client) prefix arguments) ;; (send-pong client (first arguments))) --

Private

Undocumented

WITH-CLIENT-STREAM ((VAR CLIENT) &BODY BODY)

GENERIC-FUNCTION

Public

CONNECT (CLIENT)

Connect and register /client/ with an IRC server. This also sets up some of the slots, and opens the log-stream.

CONNECTED-P (CLIENT)

Return `t' if /client/ is connected, `nil' otherwise.

DISCONNECT (CLIENT &KEY MESSAGE (MESSAGE *DEFAULT-QUIT-MESSAGE*))

Send QUIT message to server, close the socket and close the log-stream. Always signals `connection-closed'.

HANDLE (COMMAND CLIENT PREFIX ARGUMENTS)

Called by `receive-message' after parsing the raw message. Specialize this with the macro `define-handler' for customizing the behaviour. There is a default method that spits out the unhandled message to `*standard-output*'.

RECEIVE-MESSAGE (CLIENT)

Read a message from /connnection/, parse it, `handle', and return the parsed bits. The return value is a list with (/raw-prefix/ /command/ /parsed-parameters/), where - /raw-prefix/ is the raw prefix string, or `nil' if prefix wasn't present, - /command/ is a keyword with a name corresponding to the command from the RFC and - /parsed-parameters/ is a list of strings representing the arguments in the message. If an error occurs during the reading, the client will be disconnected, and the `connection-closed' will be signalled.

SEND-JOIN (CLIENT CHANNEL &KEY PASSWORD)

Send JOIN message.

SEND-PONG (CLIENT MESSAGE)

Send PONG command to server.

SEND-PRIVMSG (CLIENT VICTIM MESSAGE)

Send /message/ to /victim/. /victim/ can be either a channel-name or a nickname.

Private

CHANGE-NICK (CLIENT NEW-NICKNAME)

Send NICK message to server, and set the `nickname' of /client.

SLOT-ACCESSOR

Public

NICKNAME (CLIENT)

The Return current nickname of /client/.

Private

SOCKET (CLIENT)

The Return the /client/'s socket.

VARIABLE

Private

Undocumented

*DEFAULT-QUIT-MESSAGE*

*MESSAGE-SCANNER*

*REPLY-NUMBER->REPLY-NAME*

*VERSION*

CLASS

Public

CLIENT

A client connection to an IRC server. Valid initargs are: - `:nickname' -- the nickname use when connecting (required) - `:server' -- the hostname of the server to connect to as a string (required) - `:port' -- the port to connect to as an integer (optional) - `:username' -- the username to register with (optional) - `:realname' -- the realname to register with (optional) - `:password' -- the password to regiseter with (optional) - `:log-pathname' -- pathname for packet-log pathname (optional) Please note that you call `connect' on an instance of `client', instead of having `connect' return a an instance instance.

CONDITION

Public

CONNECTION-CLOSED

Signalled by `disconnect'. Disconnecting is the default action whenever an error occurs, so this signal can for example be handled to reconnect.

CONNECTION-FAILED

Signalled by `connect'.

CONNECTION-LOST

Signalled when connection is lost. Currently signalled when an error occurs during trying to receive a message from the server.