source: project/wiki/eggref/4/gopher @ 13270

Last change on this file since 13270 was 13270, checked in by Jim Ursetto, 12 years ago

Changes applied for zbigniew (71.201.84.72) through svnwiki:

Add gopher egg wiki entry

File size: 3.7 KB
Line 
1[[tags: egg]]
2
3== gopher
4
5[[toc:]]
6
7=== Synopsis
8
9gopher is a simple interface to the Gopher protocol.
10
11=== Overview
12
13The gopher extension provides the minimum interface required to
14communicate with Gopher clients.
15You may create and send records consisting of the five fields {{(type
16name selector host port)}}, send text and binary files, even send
17arbitrary lines; finally, there is a procedure to parse a line sent by
18the client and pass it to a user-specified handler.
19
20The [[phricken]] egg relies on this module, providing a much more
21high-level interface and a full networked Gopher server.
22
23=== Interface
24
25==== Notes
26
27All transmission is done on {{(current-input-port)}} and
28{{(current-output-port)}}.  This extension does not know or care about the
29network.
30
31All {{send-*}} procedures are specified to return {{#t}}.
32
33==== make-entry
34
35<procedure>(make-entry type name selector host port)</procedure>
36
37Create a record consisting of the five main fields in RFC 1436.  The
38fields may be of any type, as they are converted to strings via
39{{->string}} before sending.
40
41Example: {{(make-entry 'I "Picture of me" "/me.jpg" (get-host-name) 70)}}
42
43Also provided is the record predicate {{entry?}}.
44
45==== entry->string
46
47<procedure>(entry->string e)</procedure>
48
49Converts an entry record to a string, using the following rules:
50
51* Entry fields are converted to strings via {{->string}}
52* CR, LF, TAB and NUL are replaced with SPACE
53* Only the first character of the {{type}} field string is used
54* Output string format is "TypeName<TAB>Selector<TAB>Host<TAB>Port"
55
56==== send-entry
57
58<procedure>(send-entry e)</procedure>
59
60Send an entry record to the client.  Equivalent to {{(send-line (entry->string e))}}.
61
62==== send-line
63
64<procedure>(send-line line)</procedure>
65
66Send a single line to the client, and terminate it with a CRLF. 
67
68The constant {{eol}} is also provided which is just the string "\r\n".
69
70==== send-lastline
71
72<procedure>(send-lastline)</procedure>
73
74Send an end-of-transmission indicator to the client, which is simply a
75period on a line by itself.
76
77==== send-text-file
78
79<procedure>(send-text-file filename)</procedure>
80
81Read text file {{FILENAME}} and send it to the client, with a {{CRLF}}
82terminating each line.  A period at the beginning of a line will be
83escaped (doubled).  A lone period is sent at the end, via {{(send-lastline)}}.
84
85==== send-binary-file
86
87<procedure>(send-binary-file filename)</procedure>
88
89Send a binary file verbatim to the client, using the sendfile module.  No lastline is sent.
90
91==== accept
92
93<procedure>(accept handle-request)</procedure>
94<parameter>(max-line-length 2048)</parameter>
95
96Reads a line from the client (up to CRLF, plain CR, or plain LF),
97replaces any ASCII NULs with SPACE, and splits the line into fields,
98using TAB as the delimiter.  In general, client lines take 4 forms:
99
100* {{Selector}}
101* {{Selector<TAB>Search terms}}
102* {{Selector<TAB>Gopher+ data}}
103* {{Selector<TAB>Gopher+ data<TAB>Search terms}}
104
105The first field is always the requested selector.  Search terms are
106added for type 7 requests.  The Gopher+ protocol unfortunately
107introduces some context-sensitive ambiguity into the meaning of the
108fields, and this module is not in the business of figuring that out.
109Instead, the user is expected to hash out the meaning of any extra
110fields, and {{handle-request}} is therefore called with two arguments:
111
112 (handle-request (car fields) (cdr fields))
113 (handle-request selector extra)            ; put another way
114
115Note: the RFC says selectors may not exceed 255 characters, but this
116check is not enforced; however, to avoid memory overflow, {{accept}}
117will only read up to max-line-length characters.  (Special note:
118line limiting doesn't currently work for TCP ports!)
119
120=== Examples
121
122See the [[phricken]] extension for an example.
123
124=== Author
125
126Jim Ursetto
127
128=== License
129
130BSD
131
Note: See TracBrowser for help on using the repository browser.