The trivial-nntp Reference Manual

This is the trivial-nntp Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 07:26:46 2022 GMT+0.

1 Introduction

:trivial-nntp (:tnntp)

Common lisp tools for connecting to and crawling around NNTP servers. It uses usocket and cl+ssl, and therefore handles simple or SSL-encrypted NNTP connections.

This is a minimalistic effort; however watch this:

     CL-USER> (in-package :tnntp)
     TNNTP> (command "HELP")
     "100 Legal commands^M"
     1
     TNNTP> (rlist)
     "  ARTICLE [message-ID|number]^M"
     "  AUTHINFO USER name|PASS password|GENERIC program [argument ...]^M"
     "  BODY [message-ID|number]^M" "  CAPABILITIES [keyword]^M"
     "  COMPRESS DEFLATE^M" "  DATE^M" "  GROUP newsgroup^M"
     "..."
     "Report problems to <usenet@fleegle.mixmin.net>.^M"
     TNNTP> (disconnect)
     "205 Bye!^M"
     2
     CL-USER>

This simple test connect to news.mixmin.net (see tnntp.lisp). To connect to your server, create a server just like this (with your own info, of course):

(defparameter *server* ;; or keep this in some other place...
  (make-server :name "news.mixmin.net"
	       :port 119
	       :user nil
	       :password nil
	       :ssl nil
	       )
(defparameter *conn* ;; or create an array of connections or whatever
  (make-conn :server *server* :group "alt.whatever")

At the core, the server structure (see 'tnntp.lisp') contains information about the URL, port, authentication. A connection keeps track of the socket/stream state. The system will transparently reconnect and restore current group on a connection should the server close the connection.

Commands are sent with something like (command connection "commandstring" :expecting 2 ) The expecting parameter, if specified, makes sure that the response in in 200-299 range (only first digit is checked). For commands with an additional parameter such as "GROUP groupname" the :also parameter avoids building command strings: (send-command "GROUP" :also groupname)

Responses are read with

(rline) - read one line
(rlist) - read lines terminated by ".^M" into a list; optionally process with :proc.

Lines are returned unprocessed, with control-M character. Rationale: you will probably parse the lines anyway, so there is little reason to worry about that.

WORKFLOW

Create a server structure with your server url, port and authentication info.
Create a connection structure with the server.
(command ...) "MODE READER" is a good start. If you send commands that return data, make sure to read everything up to and including the termination line containing a single dot. See (rlist) for details. If you don't you will get out of sync and send-command will not get a good response line.
(disconnect) when done -- it sends "QUIT" and kills the sockets
Write a news transport, a reader, a downloader, or anything that you are discouraged to do in this article

A SIMPLE EXAMPLE

(load-groups)
(search-groups "book")

Search the grouplist for anything containing the word 'book'; regex expressions allowed!

References: *

2 Systems

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

trivial-nntp

2.1 `trivial-nntp`

Simple tools for interfacing to NNTP servers

Author

Stacksmith <fpgasm@apple2.x10.mx>

License

MIT

Dependencies

usocket (system).
cl+ssl (system).

Source

trivial-nntp.asd.

Child Components

package.lisp (file).
tnntp.lisp (file).

3 Files

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

Lisp

3.1.1 `trivial-nntp/trivial-nntp.asd`

Source: trivial-nntp.asd.
Parent Component: trivial-nntp (system).
ASDF Systems: trivial-nntp.

3.1.2 `trivial-nntp/package.lisp`

Source: trivial-nntp.asd.
Parent Component: trivial-nntp (system).
Packages: trivial-nntp.

3.1.3 `trivial-nntp/tnntp.lisp`

Dependency

package.lisp (file).

Source

trivial-nntp.asd.

Parent Component

trivial-nntp (system).

Public Interface

*conn* (special variable).
*server* (special variable).
command (function).
conn (structure).
conn-bytes-read (reader).
(setf conn-bytes-read) (writer).
conn-group (reader).
(setf conn-group) (writer).
conn-server (reader).
(setf conn-server) (writer).
conn-stream (reader).
(setf conn-stream) (writer).
disconnect (function).
make-conn (function).
make-server (function).
nntp-error (function).
nntp-error (condition).
print-object (method).
range (function).
reconnect (function).
rline (function).
rlist (function).
server (structure).
server-groups (reader).
(setf server-groups) (writer).
server-name (reader).
(setf server-name) (writer).
server-password (reader).
(setf server-password) (writer).
server-port (reader).
(setf server-port) (writer).
server-ssl (reader).
(setf server-ssl) (writer).
server-user (reader).
(setf server-user) (writer).

Internals

conn-p (function).
copy-conn (function).
copy-server (function).
line-or-nil (function).
nntp-error-message (reader method).
(setf nntp-error-message) (writer method).
nntp-id (reader method).
(setf nntp-id) (writer method).
response (function).
server-maxconns (reader).
(setf server-maxconns) (writer).
server-p (function).

4 Packages

Packages are listed by definition order.

trivial-nntp

4.1 `trivial-nntp`

Source

package.lisp.

Nickname

tnntp

Use List

common-lisp.

Public Interface

*conn* (special variable).
*server* (special variable).
command (function).
conn (structure).
conn-bytes-read (reader).
(setf conn-bytes-read) (writer).
conn-group (reader).
(setf conn-group) (writer).
conn-server (reader).
(setf conn-server) (writer).
conn-stream (reader).
(setf conn-stream) (writer).
disconnect (function).
make-conn (function).
make-server (function).
nntp-error (function).
nntp-error (condition).
range (function).
reconnect (function).
rline (function).
rlist (function).
server (structure).
server-groups (reader).
(setf server-groups) (writer).
server-name (reader).
(setf server-name) (writer).
server-password (reader).
(setf server-password) (writer).
server-port (reader).
(setf server-port) (writer).
server-ssl (reader).
(setf server-ssl) (writer).
server-user (reader).
(setf server-user) (writer).

Internals

conn-p (function).
copy-conn (function).
copy-server (function).
line-or-nil (function).
nntp-error-message (generic reader).
(setf nntp-error-message) (generic writer).
nntp-id (generic reader).
(setf nntp-id) (generic writer).
response (function).
server-maxconns (reader).
(setf server-maxconns) (writer).
server-p (function).

5 Definitions

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

Public Interface
Internals

5.1 Public Interface

Special variables
Ordinary functions
Standalone methods
Conditions
Structures

5.1.1 Special variables

Special Variable: *conn* ¶

Package: trivial-nntp.
Source: tnntp.lisp.

Special Variable: *server* ¶

Package: trivial-nntp.
Source: tnntp.lisp.

5.1.2 Ordinary functions

Function: command (string &key conn expecting also also2 depth) ¶

send an NNTP command and read response. Return first digit of response and entire response string. - (commnad "XOVER" :also (range 1 10))
- (command "GROUP" :also "alt.blah.blah.blah"

Package: trivial-nntp.
Source: tnntp.lisp.

Reader: conn-bytes-read (instance) ¶

Writer: (setf conn-bytes-read) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: bytes-read.

Reader: conn-group (instance) ¶

Writer: (setf conn-group) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: group.

Reader: conn-server (instance) ¶

Writer: (setf conn-server) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: server.

Reader: conn-stream (instance) ¶

Writer: (setf conn-stream) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: stream.

Function: disconnect (&key conn) ¶

cleanly disconnect from the server

Package: trivial-nntp.
Source: tnntp.lisp.

Function: make-conn (&key server group stream bytes-read) ¶

Package: trivial-nntp.
Source: tnntp.lisp.

Function: make-server (&key name port user password ssl groups maxconns) ¶

Package: trivial-nntp.
Source: tnntp.lisp.

Function: nntp-error (id message) ¶

Package: trivial-nntp.
Source: tnntp.lisp.

Function: range (low high &key stream) ¶

output an NNTP article range to stream.

Package: trivial-nntp.
Source: tnntp.lisp.

Function: reconnect (&key conn) ¶

Reconnect to the server, if disconnected, restoring state (entering a group). This needs more work...

Package: trivial-nntp.
Source: tnntp.lisp.

Function: rline (&key conn) ¶

return a unit (line) of text or nil for NNTP endline

Package: trivial-nntp.
Source: tnntp.lisp.

Function: rlist (&key conn proc) ¶

collect a list containing lines of data, processing if requested

Package: trivial-nntp.
Source: tnntp.lisp.

Reader: server-groups (instance) ¶

Writer: (setf server-groups) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: groups.

Reader: server-name (instance) ¶

Writer: (setf server-name) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: name.

Reader: server-password (instance) ¶

Writer: (setf server-password) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: password.

Reader: server-port (instance) ¶

Writer: (setf server-port) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: port.

Reader: server-ssl (instance) ¶

Writer: (setf server-ssl) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: ssl.

Reader: server-user (instance) ¶

Writer: (setf server-user) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: user.

5.1.3 Standalone methods

Method: print-object ((object server) stream) ¶

Source: tnntp.lisp.

5.1.4 Conditions

Condition: nntp-error ¶

Package

trivial-nntp.

Source

tnntp.lisp.

Direct superclasses

error.

Direct methods

(setf nntp-error-message).
nntp-error-message.
(setf nntp-id).
nntp-id.

Direct slots

Slot: message ¶

text message indicating nntp error

Initform: (quote nil)
Initargs: :message
Readers: nntp-error-message.
Writers: (setf nntp-error-message).

Slot: id ¶

Initform: (quote nil)
Initargs: :id
Readers: nntp-id.
Writers: (setf nntp-id).

5.1.5 Structures

Structure: conn ¶

Package

trivial-nntp.

Source

tnntp.lisp.

Direct superclasses

structure-object.

Direct slots

Slot: server ¶

Readers: conn-server.
Writers: (setf conn-server).

Slot: group ¶

Readers: conn-group.
Writers: (setf conn-group).

Slot: stream ¶

Package: common-lisp.
Initform: 0
Readers: conn-stream.
Writers: (setf conn-stream).

Slot: bytes-read ¶

Initform: 0
Readers: conn-bytes-read.
Writers: (setf conn-bytes-read).

Structure: server ¶

Package

trivial-nntp.

Source

tnntp.lisp.

Direct superclasses

structure-object.

Direct methods

print-object.

Direct slots

Slot: name ¶

Readers: server-name.
Writers: (setf server-name).

Slot: port ¶

Initform: 119
Readers: server-port.
Writers: (setf server-port).

Slot: user ¶

Readers: server-user.
Writers: (setf server-user).

Slot: password ¶

Readers: server-password.
Writers: (setf server-password).

Slot: ssl ¶

Readers: server-ssl.
Writers: (setf server-ssl).

Slot: groups ¶

Readers: server-groups.
Writers: (setf server-groups).

Slot: maxconns ¶

Initform: 1
Readers: server-maxconns.
Writers: (setf server-maxconns).

5.2 Internals

Ordinary functions
Generic functions

5.2.1 Ordinary functions

Function: conn-p (object) ¶

Package: trivial-nntp.
Source: tnntp.lisp.

Function: copy-conn (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.

Function: copy-server (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.

Function: line-or-nil (line) ¶

return nil for NNTP endline

Package: trivial-nntp.
Source: tnntp.lisp.

Function: response (&key conn expecting) ¶

return first digit of the code and the entire line

Package: trivial-nntp.
Source: tnntp.lisp.

Reader: server-maxconns (instance) ¶

Writer: (setf server-maxconns) (instance) ¶

Package: trivial-nntp.
Source: tnntp.lisp.
Target Slot: maxconns.

Function: server-p (object) ¶

Package: trivial-nntp.
Source: tnntp.lisp.

5.2.2 Generic functions

Generic Reader: nntp-error-message (condition) ¶

Generic Writer: (setf nntp-error-message) (condition) ¶

Package

trivial-nntp.

Methods

Reader Method: nntp-error-message ((condition nntp-error)) ¶

Writer Method: (setf nntp-error-message) ((condition nntp-error)) ¶

Source: tnntp.lisp.
Target Slot: message.

Generic Reader: nntp-id (condition) ¶

Generic Writer: (setf nntp-id) (condition) ¶

Package

trivial-nntp.

Methods

Reader Method: nntp-id ((condition nntp-error)) ¶

Writer Method: (setf nntp-id) ((condition nntp-error)) ¶

Source: tnntp.lisp.
Target Slot: id.

Appendix A Indexes

Concepts
Functions
Variables
Data types

A.1 Concepts

A.2 Functions

Jump to:	( C D F G L M N P R S

	Index Entry	Section

(
	`(setf conn-bytes-read)`:	Public ordinary functions
	`(setf conn-group)`:	Public ordinary functions
	`(setf conn-server)`:	Public ordinary functions
	`(setf conn-stream)`:	Public ordinary functions
	`(setf nntp-error-message)`:	Private generic functions
	`(setf nntp-error-message)`:	Private generic functions
	`(setf nntp-id)`:	Private generic functions
	`(setf nntp-id)`:	Private generic functions
	`(setf server-groups)`:	Public ordinary functions
	`(setf server-maxconns)`:	Private ordinary functions
	`(setf server-name)`:	Public ordinary functions
	`(setf server-password)`:	Public ordinary functions
	`(setf server-port)`:	Public ordinary functions
	`(setf server-ssl)`:	Public ordinary functions
	`(setf server-user)`:	Public ordinary functions

C
	`command`:	Public ordinary functions
	`conn-bytes-read`:	Public ordinary functions
	`conn-group`:	Public ordinary functions
	`conn-p`:	Private ordinary functions
	`conn-server`:	Public ordinary functions
	`conn-stream`:	Public ordinary functions
	`copy-conn`:	Private ordinary functions
	`copy-server`:	Private ordinary functions

D
	`disconnect`:	Public ordinary functions

F
	`Function, (setf conn-bytes-read)`:	Public ordinary functions
	`Function, (setf conn-group)`:	Public ordinary functions
	`Function, (setf conn-server)`:	Public ordinary functions
	`Function, (setf conn-stream)`:	Public ordinary functions
	`Function, (setf server-groups)`:	Public ordinary functions
	`Function, (setf server-maxconns)`:	Private ordinary functions
	`Function, (setf server-name)`:	Public ordinary functions
	`Function, (setf server-password)`:	Public ordinary functions
	`Function, (setf server-port)`:	Public ordinary functions
	`Function, (setf server-ssl)`:	Public ordinary functions
	`Function, (setf server-user)`:	Public ordinary functions
	`Function, command`:	Public ordinary functions
	`Function, conn-bytes-read`:	Public ordinary functions
	`Function, conn-group`:	Public ordinary functions
	`Function, conn-p`:	Private ordinary functions
	`Function, conn-server`:	Public ordinary functions
	`Function, conn-stream`:	Public ordinary functions
	`Function, copy-conn`:	Private ordinary functions
	`Function, copy-server`:	Private ordinary functions
	`Function, disconnect`:	Public ordinary functions
	`Function, line-or-nil`:	Private ordinary functions
	`Function, make-conn`:	Public ordinary functions
	`Function, make-server`:	Public ordinary functions
	`Function, nntp-error`:	Public ordinary functions
	`Function, range`:	Public ordinary functions
	`Function, reconnect`:	Public ordinary functions
	`Function, response`:	Private ordinary functions
	`Function, rline`:	Public ordinary functions
	`Function, rlist`:	Public ordinary functions
	`Function, server-groups`:	Public ordinary functions
	`Function, server-maxconns`:	Private ordinary functions
	`Function, server-name`:	Public ordinary functions
	`Function, server-p`:	Private ordinary functions
	`Function, server-password`:	Public ordinary functions
	`Function, server-port`:	Public ordinary functions
	`Function, server-ssl`:	Public ordinary functions
	`Function, server-user`:	Public ordinary functions

G
	`Generic Function, (setf nntp-error-message)`:	Private generic functions
	`Generic Function, (setf nntp-id)`:	Private generic functions
	`Generic Function, nntp-error-message`:	Private generic functions
	`Generic Function, nntp-id`:	Private generic functions

L
	`line-or-nil`:	Private ordinary functions

M
	`make-conn`:	Public ordinary functions
	`make-server`:	Public ordinary functions
	`Method, (setf nntp-error-message)`:	Private generic functions
	`Method, (setf nntp-id)`:	Private generic functions
	`Method, nntp-error-message`:	Private generic functions
	`Method, nntp-id`:	Private generic functions
	`Method, print-object`:	Public standalone methods

N
	`nntp-error`:	Public ordinary functions
	`nntp-error-message`:	Private generic functions
	`nntp-error-message`:	Private generic functions
	`nntp-id`:	Private generic functions
	`nntp-id`:	Private generic functions

P
	`print-object`:	Public standalone methods

R
	`range`:	Public ordinary functions
	`reconnect`:	Public ordinary functions
	`response`:	Private ordinary functions
	`rline`:	Public ordinary functions
	`rlist`:	Public ordinary functions

S
	`server-groups`:	Public ordinary functions
	`server-maxconns`:	Private ordinary functions
	`server-name`:	Public ordinary functions
	`server-p`:	Private ordinary functions
	`server-password`:	Public ordinary functions
	`server-port`:	Public ordinary functions
	`server-ssl`:	Public ordinary functions
	`server-user`:	Public ordinary functions

Jump to:	( C D F G L M N P R S

A.3 Variables

Jump to:	* B G I M N P S U

	Index Entry	Section

*
	`conn`:	Public special variables
	`server`:	Public special variables

B
	`bytes-read`:	Public structures

G
	`group`:	Public structures
	`groups`:	Public structures

I
	`id`:	Public conditions

M
	`maxconns`:	Public structures
	`message`:	Public conditions

N
	`name`:	Public structures

P
	`password`:	Public structures
	`port`:	Public structures

S
	`server`:	Public structures
	`Slot, bytes-read`:	Public structures
	`Slot, group`:	Public structures
	`Slot, groups`:	Public structures
	`Slot, id`:	Public conditions
	`Slot, maxconns`:	Public structures
	`Slot, message`:	Public conditions
	`Slot, name`:	Public structures
	`Slot, password`:	Public structures
	`Slot, port`:	Public structures
	`Slot, server`:	Public structures
	`Slot, ssl`:	Public structures
	`Slot, stream`:	Public structures
	`Slot, user`:	Public structures
	`Special Variable, conn`:	Public special variables
	`Special Variable, server`:	Public special variables
	`ssl`:	Public structures
	`stream`:	Public structures

U
	`user`:	Public structures

Jump to:	* B G I M N P S U

A.4 Data types

Jump to:	C F N P S T

	Index Entry	Section

C
	`Condition, nntp-error`:	Public conditions
	`conn`:	Public structures

F
	`File, package.lisp`:	The trivial-nntp/package․lisp file
	`File, tnntp.lisp`:	The trivial-nntp/tnntp․lisp file
	`File, trivial-nntp.asd`:	The trivial-nntp/trivial-nntp․asd file

N
	`nntp-error`:	Public conditions

P
	`Package, trivial-nntp`:	The trivial-nntp package
	`package.lisp`:	The trivial-nntp/package․lisp file

S
	`server`:	Public structures
	`Structure, conn`:	Public structures
	`Structure, server`:	Public structures
	`System, trivial-nntp`:	The trivial-nntp system

T
	`tnntp.lisp`:	The trivial-nntp/tnntp․lisp file
	`trivial-nntp`:	The trivial-nntp system
	`trivial-nntp`:	The trivial-nntp package
	`trivial-nntp.asd`:	The trivial-nntp/trivial-nntp․asd file

Jump to:	C F N P S T

The trivial-nntp Reference Manual

The trivial-nntp Reference Manual

Table of Contents

1 Introduction

:trivial-nntp (:tnntp)

2 Systems

2.1 trivial-nntp

3 Files

3.1 Lisp

3.1.1 trivial-nntp/trivial-nntp.asd

3.1.2 trivial-nntp/package.lisp

3.1.3 trivial-nntp/tnntp.lisp

4 Packages

4.1 trivial-nntp

5 Definitions

5.1 Public Interface

5.1.1 Special variables

5.1.2 Ordinary functions

5.1.3 Standalone methods

5.1.4 Conditions

5.1.5 Structures

5.2 Internals

5.2.1 Ordinary functions

5.2.2 Generic functions

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types

2.1 `trivial-nntp`

3.1.1 `trivial-nntp/trivial-nntp.asd`

3.1.2 `trivial-nntp/package.lisp`

3.1.3 `trivial-nntp/tnntp.lisp`

4.1 `trivial-nntp`