The trivial-irc Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The trivial-irc Reference Manual

This is the trivial-irc Reference Manual, version 0.0.4, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:41:41 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

trivial-irc

Trivial IRC client library for Common Lisp.
API documentation is available.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 trivial-irc

Maintainer

Thomas Stenhaug <thomas.stenhaug@gmail.com>

Author

Thomas Stenhaug <thomas.stenhaug@gmail.com>

License

MIT

Description

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

Version

0.0.4

Dependencies
Source

trivial-irc.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 trivial-irc.asd

Location

trivial-irc.asd

Systems

trivial-irc (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 trivial-irc/package.lisp

Parent

trivial-irc (system)

Location

package.lisp

Packages

trivial-irc


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 trivial-irc/replies.lisp

Dependency

package.lisp (file)

Parent

trivial-irc (system)

Location

replies.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 trivial-irc/client.lisp

Dependency

replies.lisp (file)

Parent

trivial-irc (system)

Location

client.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

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 (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 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 (file)

Function: prefix-nickname PREFIX
Package

trivial-irc

Source

client.lisp (file)

Function: prefix-servername PREFIX
Package

trivial-irc

Source

client.lisp (file)

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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 (file)

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 (file)

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 (file)

Methods
Method: handle (g-command-var0 (eql ping)) (CLIENT client) PREFIX ARGUMENTS
Method: handle COMMAND (CLIENT client) PREFIX ARGUMENTS
Generic Function: nickname CLIENT

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

Package

trivial-irc

Source

client.lisp (file)

Methods
Method: nickname (CLIENT client)

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

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 (file)

Methods
Method: receive-message (CLIENT client)
Generic Function: send-join CLIENT CHANNEL &key PASSWORD

Send JOIN message.

Package

trivial-irc

Source

client.lisp (file)

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 (file)

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 (file)

Methods
Method: send-privmsg (CLIENT client) VICTIM MESSAGE

Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

Direct superclasses

condition (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 (file)

Direct superclasses

error (condition)

Direct slots
Slot: client

Client whose connection failed

Initargs

:client

Slot: error

Reason for failure

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 (file)

Direct superclasses

error (condition)

Direct slots
Slot: client

Client whose connection was lost

Initargs

:client


Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: nickname

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

Initargs

:nickname

Initform

(error "must supply :nickname")

Readers

nickname (generic function)

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

Initargs

:server

Initform

(error "must supply :server")

Slot: port

Port of client connection

Initargs

:port

Initform

6667

Slot: socket

Socket of an active connection

Initargs

:socket

Readers

socket (generic function)

Slot: log-pathname

Pathname of log-file

Initargs

:log-pathname

Slot: log-stream

Stream of log-file


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *default-quit-message*
Package

trivial-irc

Source

client.lisp (file)

Special Variable: *message-scanner*
Package

trivial-irc

Source

client.lisp (file)

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

trivial-irc

Source

replies.lisp (file)

Special Variable: *version*
Package

trivial-irc

Source

client.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: with-client-stream (VAR CLIENT) &body BODY
Package

trivial-irc

Source

client.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: .nick CLIENT

Send /client/’s nickname to server.

Called by ‘connect’ during registration.

Package

trivial-irc

Source

client.lisp (file)

Function: .password CLIENT

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

Package

trivial-irc

Source

client.lisp (file)

Function: .quit CLIENT &optional MESSAGE
Package

trivial-irc

Source

client.lisp (file)

Function: .user CLIENT

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

Called by ‘connect’ during registration.

Package

trivial-irc

Source

client.lisp (file)

Function: find-reply-name REPLY-NUMBER
Package

trivial-irc

Source

replies.lisp (file)

Function: parse-argument-string ARGUMENT-STRING
Package

trivial-irc

Source

client.lisp (file)

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 (file)

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 (file)

Function: record CLIENT STRING
Package

trivial-irc

Source

client.lisp (file)

Function: universal-time->iso-8601-string UNIVERSAL-TIME &key DETAIL
Package

trivial-irc

Source

client.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

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 (file)

Methods
Method: change-nick (CLIENT client) NEW-NICKNAME
Generic Function: socket CLIENT

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

Package

trivial-irc

Source

client.lisp (file)

Methods
Method: socket (CLIENT client)

Socket of an active connection


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, trivial-irc.asd: The trivial-irc<dot>asd file
File, Lisp, trivial-irc/client.lisp: The trivial-irc/client<dot>lisp file
File, Lisp, trivial-irc/package.lisp: The trivial-irc/package<dot>lisp file
File, Lisp, trivial-irc/replies.lisp: The trivial-irc/replies<dot>lisp file

L
Lisp File, trivial-irc.asd: The trivial-irc<dot>asd file
Lisp File, trivial-irc/client.lisp: The trivial-irc/client<dot>lisp file
Lisp File, trivial-irc/package.lisp: The trivial-irc/package<dot>lisp file
Lisp File, trivial-irc/replies.lisp: The trivial-irc/replies<dot>lisp file

T
trivial-irc.asd: The trivial-irc<dot>asd file
trivial-irc/client.lisp: The trivial-irc/client<dot>lisp file
trivial-irc/package.lisp: The trivial-irc/package<dot>lisp file
trivial-irc/replies.lisp: The trivial-irc/replies<dot>lisp file

Jump to:   F   L   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

.
.nick: Internal functions
.password: Internal functions
.quit: Internal functions
.user: Internal functions

C
change-nick: Internal generic functions
change-nick: Internal generic functions
connect: Exported generic functions
connect: Exported generic functions
connected-p: Exported generic functions
connected-p: Exported generic functions

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

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

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

H
handle: Exported generic functions
handle: Exported generic functions
handle: Exported generic functions

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

N
nickname: Exported generic functions
nickname: Exported generic functions

P
parse-argument-string: Internal functions
parse-prefix: Exported functions
parse-raw-message: Internal functions
prefix-nickname: Exported functions
prefix-servername: Exported functions

R
receive-message: Exported generic functions
receive-message: Exported generic functions
receive-raw-message: Internal functions
record: Internal functions

S
send-join: Exported generic functions
send-join: Exported generic functions
send-pong: Exported generic functions
send-pong: Exported generic functions
send-privmsg: Exported generic functions
send-privmsg: Exported generic functions
send-raw-message: Exported functions
socket: Internal generic functions
socket: Internal generic functions

U
universal-time->iso-8601-string: Internal functions

W
with-client-stream: Internal macros

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
C   E   L   N   P   R   S   U  
Index Entry  Section

*
*default-quit-message*: Internal special variables
*message-scanner*: Internal special variables
*reply-number->reply-name*: Internal special variables
*version*: Internal special variables

C
client: Exported conditions
client: Exported conditions
client: Exported conditions

E
error: Exported conditions

L
log-pathname: Exported classes
log-stream: Exported classes

N
nickname: Exported classes

P
password: Exported classes
port: Exported classes

R
realname: Exported classes

S
server: Exported classes
Slot, client: Exported conditions
Slot, client: Exported conditions
Slot, client: Exported conditions
Slot, error: Exported conditions
Slot, log-pathname: Exported classes
Slot, log-stream: Exported classes
Slot, nickname: Exported classes
Slot, password: Exported classes
Slot, port: Exported classes
Slot, realname: Exported classes
Slot, server: Exported classes
Slot, socket: Exported classes
Slot, username: Exported classes
socket: Exported classes
Special Variable, *default-quit-message*: Internal special variables
Special Variable, *message-scanner*: Internal special variables
Special Variable, *reply-number->reply-name*: Internal special variables
Special Variable, *version*: Internal special variables

U
username: Exported classes

Jump to:   *  
C   E   L   N   P   R   S   U  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S   T  
Index Entry  Section

C
Class, client: Exported classes
client: Exported classes
Condition, connection-closed: Exported conditions
Condition, connection-failed: Exported conditions
Condition, connection-lost: Exported conditions
connection-closed: Exported conditions
connection-failed: Exported conditions
connection-lost: Exported conditions

P
Package, trivial-irc: The trivial-irc package

S
System, trivial-irc: The trivial-irc system

T
trivial-irc: The trivial-irc system
trivial-irc: The trivial-irc package

Jump to:   C   P   S   T