The trivial-irc Reference Manual

This is the trivial-irc Reference Manual, version 0.0.4, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:57:01 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 trivial-irc

A trivial IRC client library with simple facilities for
receiving, handling and sending messages, and without facilities for CTCP.

Maintainer

Thomas Stenhaug <>

Author

Thomas Stenhaug <>

License

MIT

Version

0.0.4

Dependencies
  • cl-ppcre (system).
  • split-sequence (system).
  • usocket (system).
Source

trivial-irc.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 trivial-irc/trivial-irc.asd

Source

trivial-irc.asd.

Parent Component

trivial-irc (system).

ASDF Systems

trivial-irc.


3.1.2 trivial-irc/package.lisp

Source

trivial-irc.asd.

Parent Component

trivial-irc (system).

Packages

trivial-irc.


3.1.3 trivial-irc/replies.lisp

Dependency

package.lisp (file).

Source

trivial-irc.asd.

Parent Component

trivial-irc (system).

Internals

3.1.4 trivial-irc/client.lisp

Dependency

replies.lisp (file).

Source

trivial-irc.asd.

Parent Component

trivial-irc (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 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.

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: define-handler ((command class-spec prefix-var arguments-var) &body body)

Define handling for @c(command).

This is currently a convenience for specializing on the generic function @c(handle). An example is the handler for PING messages (which by default is the only handler specialization).

@begin[lang=lisp](code)
(define-handler (:ping client prefix arguments)
(send-pong client (first arguments)))
@end(code)

If you wanted to use a different variable-name for the client variable, you could also have written it as

@begin[lang=lisp](code)
(define-handler (:ping (client client) prefix arguments) (send-pong client (first arguments)))
@end(code)

Package

trivial-irc.

Source

client.lisp.


5.1.2 Ordinary functions

Function: parse-prefix (prefix)

Return a list of the components in prefix.

The elements of the list are as follows: @begin(list)
@item(servername or nickname as string) @item(username string, or @c(nil)) @item(a hostname string, or @c(nil)) @end(list)

Package

trivial-irc.

Source

client.lisp.

Function: prefix-nickname (prefix)
Package

trivial-irc.

Source

client.lisp.

Function: prefix-servername (prefix)
Package

trivial-irc.

Source

client.lisp.

Function: send-raw-message (client raw-message)

Send @cl:param(raw-message) and CRLF to the socket associated with @cl:param(client).

Outside of the few send-* functions, this is what you have to use to
send messages to the server.

Package

trivial-irc.

Source

client.lisp.


5.1.3 Generic functions

Generic Function: connect (client)

Connect and register @cl:param(client) with an IRC server.

This also sets up some of the slots, and opens the log-stream.

Package

trivial-irc.

Source

client.lisp.

Methods
Method: connect ((client client))
Generic Function: connected-p (client)

Return @c(t) if @cl:param(client) is connected, @c(nil) otherwise.

Package

trivial-irc.

Source

client.lisp.

Methods
Method: connected-p ((client client))
Generic Function: disconnect (client &key message)

Send QUIT message to server, close the socket and close the log-stream.

Always signals @c(connection-closed).

Package

trivial-irc.

Source

client.lisp.

Methods
Method: disconnect ((client client) &key message)
Generic Function: handle (command client prefix arguments)

Called by @c(receive-message) after parsing the raw message.

Specialize on this function with the macro @c(define-handler) for customizing behaviour.

There is a default method that spits out the unhandled message
to @c(*standard-output*).

Package

trivial-irc.

Source

client.lisp.

Methods
Method: handle ((g-command-var0 (eql :ping)) (client client) prefix arguments)
Method: handle (command (client client) prefix arguments)
Generic Reader: nickname (client)

Return current nickname of @cl:param(client).

Package

trivial-irc.

Source

client.lisp.

Methods
Reader Method: nickname ((client client))

Nickname of client (mandatory). Sent at beginning of connection, and by @c(change-nick)

Target Slot

nickname.

Generic Function: receive-message (client)

Read a message from @i(connection), parse it,
@c(handle), and return a list with the following 3 elements:

@begin(enum)
@item(the raw prefix string, or @c(nil) if prefix wasn’t present)
@item(@i(command) is a keyword with a name corresponding to the command from the RFC and) @item(@i(parsed-parameters) is a list of strings representing the arguments in the message.) @end(enum)

If an error occurs during the reading, the client will be
disconnected, and @c(connection-closed) will be signalled.

Package

trivial-irc.

Source

client.lisp.

Methods
Method: receive-message ((client client))
Generic Function: send-join (client channel &key password)

Send JOIN message.

Package

trivial-irc.

Source

client.lisp.

Methods
Method: send-join ((client client) channel &key password)
Generic Function: send-pong (client message)

Send PONG command to server.

Package

trivial-irc.

Source

client.lisp.

Methods
Method: send-pong ((client client) message)
Generic Function: send-privmsg (client victim message)

Send @cl:param(message) to @cl:param(victim), where @cl:param(victim) is either a channel- or nick-name.

Package

trivial-irc.

Source

client.lisp.

Methods
Method: send-privmsg ((client client) victim message)

5.1.4 Conditions

Condition: connection-closed

Signalled by the @c(disconnect) function.

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

Package

trivial-irc.

Source

client.lisp.

Direct superclasses

condition.

Direct slots
Slot: client

Client whose connection was closed

Initargs

:client

Condition: connection-failed

Signalled by @c(connect).

Package

trivial-irc.

Source

client.lisp.

Direct superclasses

error.

Direct slots
Slot: client

Client whose connection failed

Initargs

:client

Slot: error

Reason for failure

Package

common-lisp.

Initargs

error

Condition: connection-lost

Signalled when connection is lost.

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

Package

trivial-irc.

Source

client.lisp.

Direct superclasses

error.

Direct slots
Slot: client

Client whose connection was lost

Initargs

:client


5.1.5 Classes

Class: client

A client connection to an IRC server.

Valid initargs are:

@begin(list)
@item(@c(:nickname) – the nickname use when connecting (required)) @item(@c(:server) – the hostname of the server to connect to as a string (required)) @item(@c(:port) – the port to connect to as an integer (optional)) @item(@c(:username) – the username to register with (optional)) @item(@c(:realname) – the realname to register with (optional)) @item(@c(:password) – the password to regiseter with (optional)) @item(@c(:log-pathname) – pathname for packet-log pathname (optional)) @end(list)

Please note that you call @c(connect) on a @c(client) instance, rather than having @c(connect) return a @c(client) instance.

Package

trivial-irc.

Source

client.lisp.

Direct methods
Direct slots
Slot: nickname

Nickname of client (mandatory). Sent at beginning of connection, and by @c(change-nick)

Initform

(error "must supply :nickname")

Initargs

:nickname

Readers

nickname.

Writers

This slot is read-only.

Slot: password

Password used during registration (optional)

Initargs

:password

Slot: username

Username sent at beginning of connection. Defaults to nickname.

Initargs

:username

Slot: realname

Realname sent at beginning of connection. Defaults to username.

Initargs

:realname

Slot: server

Address of the IRC server

Initform

(error "must supply :server")

Initargs

:server

Slot: port

Port of client connection

Initform

6667

Initargs

:port

Slot: socket

Socket of an active connection

Initargs

:socket

Readers

socket.

Writers

This slot is read-only.

Slot: log-pathname

Pathname of log-file

Initargs

:log-pathname

Slot: log-stream

Stream of log-file


5.2 Internals


5.2.1 Special variables

Special Variable: *default-quit-message*
Package

trivial-irc.

Source

client.lisp.

Special Variable: *message-scanner*
Package

trivial-irc.

Source

client.lisp.

Special Variable: *reply-number->reply-name*
Package

trivial-irc.

Source

replies.lisp.

Special Variable: *version*
Package

trivial-irc.

Source

client.lisp.


5.2.2 Macros

Macro: with-client-stream ((var client) &body body)
Package

trivial-irc.

Source

client.lisp.


5.2.3 Ordinary functions

Function: .nick (client)

Send /client/’s nickname to server.

Called by ‘connect’ during registration.

Package

trivial-irc.

Source

client.lisp.

Function: .password (client)

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

Package

trivial-irc.

Source

client.lisp.

Function: .quit (client &optional message)
Package

trivial-irc.

Source

client.lisp.

Function: .user (client)

Send /client/’s username and realname to server.

Called by ‘connect’ during registration.

Package

trivial-irc.

Source

client.lisp.

Function: find-reply-name (reply-number)
Package

trivial-irc.

Source

replies.lisp.

Function: parse-argument-string (argument-string)
Package

trivial-irc.

Source

client.lisp.

Function: parse-raw-message (raw-message)

Return a list on the form (prefix command arguments).
@begin(enum)
@item(prefix) can be @c(nil), or servername / ( nickname [ [ "!" user ] "@" host ] See also the @c(parse-prefix) function.

@item(command) is a keyword either made from the alpha-characters, or a keyword looked up with @c(find-reply-name).

@item(arguments) is a list of the command arguments.
@end(enum)

Package

trivial-irc.

Source

client.lisp.

Function: receive-raw-message (client)

Receive and return a single, raw message from @cl:param(client).

If any errors occur during the reading, the connection is silently shut down.

Package

trivial-irc.

Source

client.lisp.

Function: record (client string)
Package

trivial-irc.

Source

client.lisp.

Function: universal-time->iso-8601-string (universal-time &key detail)
Package

trivial-irc.

Source

client.lisp.


5.2.4 Generic functions

Generic Function: change-nick (client new-nickname)

Send NICK message to server, and set the @c(nickname) of @cl:param(client)

Package

trivial-irc.

Source

client.lisp.

Methods
Method: change-nick ((client client) new-nickname)
Generic Reader: socket (client)

Return the @cl:param(client)’s socket.

Package

trivial-irc.

Source

client.lisp.

Methods
Reader Method: socket ((client client))

Socket of an active connection

Target Slot

socket.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   .  
C   D   F   G   H   M   N   P   R   S   U   W  
Index Entry  Section

.
.nick: Private ordinary functions
.password: Private ordinary functions
.quit: Private ordinary functions
.user: Private ordinary functions

C
change-nick: Private generic functions
change-nick: Private generic functions
connect: Public generic functions
connect: Public generic functions
connected-p: Public generic functions
connected-p: Public generic functions

D
define-handler: Public macros
disconnect: Public generic functions
disconnect: Public generic functions

F
find-reply-name: Private ordinary functions
Function, .nick: Private ordinary functions
Function, .password: Private ordinary functions
Function, .quit: Private ordinary functions
Function, .user: Private ordinary functions
Function, find-reply-name: Private ordinary functions
Function, parse-argument-string: Private ordinary functions
Function, parse-prefix: Public ordinary functions
Function, parse-raw-message: Private ordinary functions
Function, prefix-nickname: Public ordinary functions
Function, prefix-servername: Public ordinary functions
Function, receive-raw-message: Private ordinary functions
Function, record: Private ordinary functions
Function, send-raw-message: Public ordinary functions
Function, universal-time->iso-8601-string: Private ordinary functions

G
Generic Function, change-nick: Private generic functions
Generic Function, connect: Public generic functions
Generic Function, connected-p: Public generic functions
Generic Function, disconnect: Public generic functions
Generic Function, handle: Public generic functions
Generic Function, nickname: Public generic functions
Generic Function, receive-message: Public generic functions
Generic Function, send-join: Public generic functions
Generic Function, send-pong: Public generic functions
Generic Function, send-privmsg: Public generic functions
Generic Function, socket: Private generic functions

H
handle: Public generic functions
handle: Public generic functions
handle: Public generic functions

M
Macro, define-handler: Public macros
Macro, with-client-stream: Private macros
Method, change-nick: Private generic functions
Method, connect: Public generic functions
Method, connected-p: Public generic functions
Method, disconnect: Public generic functions
Method, handle: Public generic functions
Method, handle: Public generic functions
Method, nickname: Public generic functions
Method, receive-message: Public generic functions
Method, send-join: Public generic functions
Method, send-pong: Public generic functions
Method, send-privmsg: Public generic functions
Method, socket: Private generic functions

N
nickname: Public generic functions
nickname: Public generic functions

P
parse-argument-string: Private ordinary functions
parse-prefix: Public ordinary functions
parse-raw-message: Private ordinary functions
prefix-nickname: Public ordinary functions
prefix-servername: Public ordinary functions

R
receive-message: Public generic functions
receive-message: Public generic functions
receive-raw-message: Private ordinary functions
record: Private ordinary functions

S
send-join: Public generic functions
send-join: Public generic functions
send-pong: Public generic functions
send-pong: Public generic functions
send-privmsg: Public generic functions
send-privmsg: Public generic functions
send-raw-message: Public ordinary functions
socket: Private generic functions
socket: Private generic functions

U
universal-time->iso-8601-string: Private ordinary functions

W
with-client-stream: Private macros