The trivial-nntp Reference Manual

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

The trivial-nntp Reference Manual

This is the trivial-nntp Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 06:03:53 2022 GMT+0.

Table of Contents


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

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: *


2 Systems

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


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

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

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   [Contents][Index]

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
Internals

4 Packages

Packages are listed by definition order.


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

4.1 trivial-nntp

Source

package.lisp.

Nickname

tnntp

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


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


Previous: , Up: Public Interface   [Contents][Index]

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


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

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


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

A.1 Concepts


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

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