The trivial-nntp Reference Manual

Table of Contents

The trivial-nntp Reference Manual

This is the trivial-nntp Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 12:29:59 2020 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

1. Create a server structure with your server url, port and authentication info.
2. Create a connection structure with the server.
3. (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.
4. (disconnect) when done -- it sends "QUIT" and kills the sockets
5. 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: *

• USOCKET API
• RFC 977: Network News Transfer Protocol (1986)
• RFC 1036: Standard for Interchange of USENET Messages (1987)
• Don't Write a Newsreader (1995)

2 Systems

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

2.1 trivial-nntp

Author

Stacksmith <fpgasm@apple2.x10.mx>

License

MIT

Description

Simple tools for interfacing to NNTP servers

Dependencies

• usocket
• cl+ssl

Source

trivial-nntp.asd (file)

Components

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

3 Files

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

3.1 Lisp

3.1.1 trivial-nntp.asd

Location

trivial-nntp.asd

Systems

trivial-nntp (system)

3.1.2 trivial-nntp/package.lisp

Parent

trivial-nntp (system)

Location

package.lisp

Packages

trivial-nntp

3.1.3 trivial-nntp/tnntp.lisp

Dependency

package.lisp (file)

Parent

trivial-nntp (system)

Location

tnntp.lisp

Exported Definitions

• *conn* (special variable)
• *server* (special variable)
• command (function)
• conn (structure)
• conn-bytes-read (function)
• (setf conn-bytes-read) (function)
• conn-group (function)
• (setf conn-group) (function)
• conn-server (function)
• (setf conn-server) (function)
• conn-stream (function)
• (setf conn-stream) (function)
• 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 (function)
• (setf server-groups) (function)
• server-name (function)
• (setf server-name) (function)
• server-password (function)
• (setf server-password) (function)
• server-port (function)
• (setf server-port) (function)
• server-ssl (function)
• (setf server-ssl) (function)
• server-user (function)
• (setf server-user) (function)

Internal Definitions

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

4 Packages

Packages are listed by definition order.

4.1 trivial-nntp

Source

package.lisp (file)

Nickname

tnntp

Use List

common-lisp

Exported Definitions

• *conn* (special variable)
• *server* (special variable)
• command (function)
• conn (structure)
• conn-bytes-read (function)
• (setf conn-bytes-read) (function)
• conn-group (function)
• (setf conn-group) (function)
• conn-server (function)
• (setf conn-server) (function)
• conn-stream (function)
• (setf conn-stream) (function)
• 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 (function)
• (setf server-groups) (function)
• server-name (function)
• (setf server-name) (function)
• server-password (function)
• (setf server-password) (function)
• server-port (function)
• (setf server-port) (function)
• server-ssl (function)
• (setf server-ssl) (function)
• server-user (function)
• (setf server-user) (function)

Internal Definitions

• conn-p (function)
• copy-conn (function)
• copy-server (function)
• line-or-nil (function)
• nntp-error-message (generic function)
• nntp-error-message (method)
• (setf nntp-error-message) (method)
• (setf nntp-error-message) (generic function)
• nntp-id (generic function)
• nntp-id (method)
• (setf nntp-id) (method)
• (setf nntp-id) (generic function)
• response (function)
• server-maxconns (function)
• (setf server-maxconns) (function)
• server-p (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *conn*

Package

trivial-nntp

Source

tnntp.lisp (file)

Special Variable: *server*

Package

trivial-nntp

Source

tnntp.lisp (file)

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

Function: conn-bytes-read INSTANCE

Function: (setf conn-bytes-read) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: conn-group INSTANCE

Function: (setf conn-group) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: conn-server INSTANCE

Function: (setf conn-server) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: conn-stream INSTANCE

Function: (setf conn-stream) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: disconnect &key CONN

cleanly disconnect from the server

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: make-conn &key (SERVER SERVER) (GROUP GROUP) (STREAM STREAM) (BYTES-READ BYTES-READ)

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: make-server &key (NAME NAME) (PORT PORT) (USER USER) (PASSWORD PASSWORD) (SSL SSL) (GROUPS GROUPS) (MAXCONNS MAXCONNS)

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: nntp-error ID MESSAGE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: range LOW HIGH &key STREAM

output an NNTP article range to stream.

Package

trivial-nntp

Source

tnntp.lisp (file)

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

Function: rline &key CONN

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

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: rlist &key CONN PROC

collect a list containing lines of data, processing if requested

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: server-groups INSTANCE

Function: (setf server-groups) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: server-name INSTANCE

Function: (setf server-name) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: server-password INSTANCE

Function: (setf server-password) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: server-port INSTANCE

Function: (setf server-port) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: server-ssl INSTANCE

Function: (setf server-ssl) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: server-user INSTANCE

Function: (setf server-user) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

5.1.3 Conditions

Condition: nntp-error ()

Package

trivial-nntp

Source

tnntp.lisp (file)

Direct superclasses

error (condition)

Direct methods

• nntp-id (method)
• nntp-id (method)
• nntp-error-message (method)
• nntp-error-message (method)

Direct slots

Slot: message

text message indicating nntp error

Initargs

:message

Initform

(quote nil)

Readers

nntp-error-message (generic function)

Writers

(setf nntp-error-message) (generic function)

Slot: id

Initargs

:id

Initform

(quote nil)

Readers

nntp-id (generic function)

Writers

(setf nntp-id) (generic function)

5.1.4 Structures

Structure: conn ()

Package

trivial-nntp

Source

tnntp.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: server

Readers

conn-server (function)

Writers

(setf conn-server) (function)

Slot: group

Readers

conn-group (function)

Writers

(setf conn-group) (function)

Slot: stream

Initform

0

Readers

conn-stream (function)

Writers

(setf conn-stream) (function)

Slot: bytes-read

Initform

0

Readers

conn-bytes-read (function)

Writers

(setf conn-bytes-read) (function)

Structure: server ()

Package

trivial-nntp

Source

tnntp.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots

Slot: name

Readers

server-name (function)

Writers

(setf server-name) (function)

Slot: port

Initform

119

Readers

server-port (function)

Writers

(setf server-port) (function)

Slot: user

Readers

server-user (function)

Writers

(setf server-user) (function)

Slot: password

Readers

server-password (function)

Writers

(setf server-password) (function)

Slot: ssl

Readers

server-ssl (function)

Writers

(setf server-ssl) (function)

Slot: groups

Readers

server-groups (function)

Writers

(setf server-groups) (function)

Slot: maxconns

Initform

1

Readers

server-maxconns (function)

Writers

(setf server-maxconns) (function)

5.2 Internal definitions

5.2.1 Functions

Function: conn-p OBJECT

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: copy-conn INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: copy-server INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: line-or-nil LINE

return nil for NNTP endline

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: response &key CONN EXPECTING

return first digit of the code and the entire line

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: server-maxconns INSTANCE

Function: (setf server-maxconns) VALUE INSTANCE

Package

trivial-nntp

Source

tnntp.lisp (file)

Function: server-p OBJECT

Package

trivial-nntp

Source

tnntp.lisp (file)

5.2.2 Generic functions

Generic Function: nntp-error-message CONDITION

Generic Function: (setf nntp-error-message) NEW-VALUE CONDITION

Package

trivial-nntp

Methods

Method: nntp-error-message (CONDITION nntp-error)

Method: (setf nntp-error-message) NEW-VALUE (CONDITION nntp-error)

Source

tnntp.lisp (file)

Generic Function: nntp-id CONDITION

Generic Function: (setf nntp-id) NEW-VALUE CONDITION

Package

trivial-nntp

Methods

Method: nntp-id (CONDITION nntp-error)

Method: (setf nntp-id) NEW-VALUE (CONDITION nntp-error)

Source

tnntp.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types