chickadee » gopher

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

gopher

Synopsis

gopher is a simple interface to the Gopher protocol.

Overview

The gopher extension provides the minimum interface required to communicate with Gopher clients. You may create and send records consisting of the five fields (type name selector host port), send text and binary files, even send arbitrary lines; finally, there is a procedure to parse a line sent by the client and pass it to a user-specified handler.

The phricken egg relies on this module, providing a much more high-level interface and a full networked Gopher server.

Interface

Notes

All transmission is done on (current-input-port) and (current-output-port). This extension does not know or care about the network.

All send-* procedures are specified to return #t.

Procedures

make-entry type name selector host portprocedure

Create a record consisting of the five main fields in RFC 1436. The fields may be of any type, as they are converted to strings via ->string before sending.

Example: (make-entry 'I "Picture of me" "/me.jpg" (get-host-name) 70)

Also provided is the record predicate entry?.

entry->string eprocedure

Converts an entry record to a string, using the following rules:

  • Entry fields are converted to strings via ->string
  • CR, LF, TAB and NUL are replaced with SPACE
  • Only the first character of the type field string is used
  • Output string format is "TypeName<TAB>Selector<TAB>Host<TAB>Port"
send-entry eprocedure

Send an entry record to the client. Equivalent to (send-line (entry->string e)).

send-line lineprocedure

Send a single line to the client, and terminate it with a CRLF.

The constant eol is also provided which is just the string "\r\n".

send-lastlineprocedure

Send an end-of-transmission indicator to the client, which is simply a period on a line by itself.

send-text-file filenameprocedure

Read text file FILENAME and send it to the client, with a CRLF terminating each line. A period at the beginning of a line will be escaped (doubled). A lone period is sent at the end, via (send-lastline).

send-binary-file filenameprocedure

Send a binary file verbatim to the client, using the sendfile module. No lastline is sent.

accept handle-requestprocedure
max-line-length 2048parameter

Reads a line from the client (up to CRLF, plain CR, or plain LF), replaces any ASCII NULs with SPACE, and splits the line into fields, using TAB as the delimiter. In general, client lines take 4 forms:

  • Selector
  • Selector<TAB>Search terms
  • Selector<TAB>Gopher+ data
  • Selector<TAB>Gopher+ data<TAB>Search terms

The first field is always the requested selector. Search terms are added for type 7 requests. The Gopher+ protocol unfortunately introduces some context-sensitive ambiguity into the meaning of the fields, and this module is not in the business of figuring that out. Instead, the user is expected to hash out the meaning of any extra fields, and handle-request is therefore called with two arguments:

(handle-request (car fields) (cdr fields))
(handle-request selector extra)            ; put another way

Note: the RFC says selectors may not exceed 255 characters, but this check is not enforced; however, to avoid memory overflow, accept will only read up to max-line-length characters. (Special note: line limiting doesn't currently work for TCP ports!)

Examples

See the phricken extension for an example.

Author

Jim Ursetto

License

BSD

Contents »