source: project/release/3/remote-repl/trunk/doc.scm @ 11659

Last change on this file since 11659 was 11659, checked in by elf, 12 years ago

numerous small fixes, mostly reported by certainty

File size: 22.9 KB
Line 
1;;;; egg:        remote-repl
2;;;; file:       doc.scm
3;;;; author:     elf <elf@ephemeral.net>
4;;;; date:       16 Aug 2008
5;;;; purpose:    eggdoc-format documentation for remote-repl
6;;;;
7;;;; licence:    BSD (see LICENCE)
8;;;; copyright:  Copyright (C) 2008, Elf
9;;;;             All rights reserved.
10;;;;
11;;;; changelog:  20080816 [elf]  Initial release.
12;;;;
13
14
15
16(require-extension srfi-1)    ; list library
17(require-extension utils)     ; utility procedures
18(require-extension eggdoc)    ; egg documentation facility
19
20
21
22;; (table-make FORMAT-WRAPPERS HEADERS ROWS...)
23;; helper macro for constructing tables
24(define (elf-eggdoc-ss doc)
25    `((table-spec *macro* .
26        ,(lambda (tag fmtw hdrs . rows)
27            `(table (@ (style "table-layout: auto"))
28                 (tr (@ (style "vertical-align: baseline"))
29                     ,@(map
30                         (lambda (h)
31                             `(th (@ (style "padding-top: 2.5em")) ,h))
32                         hdrs))
33                     ,@(pair-fold-right
34                     (lambda (x r)
35                         (let ((t   (if (null? (cdr x))
36                                        "padding-top: 2em; padding-bottom: 2.5em"
37                                        "padding-top: 2em"))
38                               (a   (car x)))
39                             (cons
40                                 `(tr (@ (style "vertical-align: baseline"))
41                                      ,@(map
42                                          (lambda (f d)
43                                              `(td (@ (style ,t)) (,f ,d)))
44                                          fmtw a))
45                                 r)))
46                     '()
47                     rows))))
48      (inline-table-spec *macro* .
49        ,(lambda (tag fmtw hdrs . rows)
50            `(table (@ (style "inline-table; table-layout: auto"))
51                 (tr (@ (style "vertical-align: baseline"))
52                     ,@(map
53                         (lambda (h)
54                             `(th (@ (style "padding-top: 1.5em")) ,h))
55                         hdrs))
56                     ,@(pair-fold-right
57                     (lambda (x r)
58                         (let ((t   (if (null? (cdr x))
59                                        "padding-top: 1em; padding-bottom: 1.5em"
60                                        "padding-top: 1em"))
61                               (a   (car x)))
62                             (cons
63                                 `(tr (@ (style "vertical-align: baseline"))
64                                      ,@(map
65                                          (lambda (f d)
66                                              `(td (@ (style ,t)) (,f ,d)))
67                                          fmtw a))
68                                 r)))
69                     '()
70                     rows))))
71        ,@(eggdoc:make-stylesheet doc)))
72
73
74(define doc
75    `((eggdoc:begin
76        (name         "remote-repl")
77        (description  "remote read-eval-print loop client and server")
78        (author       (url "mailto:elf@ephemeral.net" "elf"))
79
80        (history
81            (version "1.0" "20080816 [elf]  Initial release.")
82            (version "1.1" "20080816 [elf]  Bumped version to 1.1 from numerous small fixes. (mostly reported by certainty)"))
83
84        (usage)
85        (download "remote-repl.egg")
86
87
88        (documentation
89
90            (p "This extension provides a safe, portable, very flexible "
91               "remote REPL facility.  The server component is fully threaded "
92               "and may be plugged into any existing codebase without "
93               "modification.  The client component is not threaded.")
94            (p "For maximum flexibility, " (u "all") " procedures involved "
95               "in the operation of these extensions may be specified.  The "
96               "default is to use the tcp extension with no authentication "
97               "and no sandboxing, but the design should make it easy to "
98               "extend (e.g. through SSL sockets, ACL authentication, "
99               "shared or unshared environments, etc) while maintaining "
100               "safety.  All conditions are caught and handled properly, and "
101               "no knowledge of threading, exception handling, or chicken "
102               "internals is required.  Just plug it in and go!")
103
104            (subsection "Server Procedures"
105                (p "For the server component, use: "
106                   (tt "(require-extension remote-repl-server)"))
107                (group
108                    (procedure
109                        "(rrepl-server-start PORTNUM [KEYARGS...])"
110                        (p "Creates a new remote-repl server and returns a "
111                           (tt "rrepl-server") " object.  The server "
112                           "automatically starts a listener thread, waiting "
113                           "for connections on " (tt "PORTNUM") ".  "
114                           (tt "KEYARGS") " are optional keyword arguments "
115                           "for extending/tuning the server's behaviour, as "
116                           "given below:")
117                        (table-spec
118                            (tt tt p)
119                            ("Keyword" "Default" "Description")
120                            ("listen" "tcp-listen"
121                             ("Procedure to create a listener for incoming "
122                              "connections.  Must take three arguments: "
123                              "an integer portnum on which to listen, "
124                              "an integer count of maximum pending "
125                              "connections, and a string (or " (tt "#f") ") "
126                              "corresponding to a hostname/IP.  The final "
127                              "string argument, if given, is the only host "
128                              "from which connections are allowed."))
129                            ("accept" "tcp-accept"
130                             ("Procedure to accept an incoming connection "
131                              "from a listener port.  Takes in a listener "
132                              "argument and returns an input port and an "
133                              "output port for the new connection."))
134                            ("clisten" "tcp-close"
135                             ("Procedure to close and release a listener "
136                              "port given as an argument."))
137                            ("auth" "identity"
138                             ("After accepting a connection with "
139                              (tt "accept") ", the " (tt "auth") " procedure "
140                              "is evaluated on the server object and the new "
141                              "session object created from the ports.  If "
142                              "the session authenticates, it is returned; "
143                              "if it does not pass, return " (tt "#f") ".  "
144                              "The REPL thread for a session is not started "
145                              "until after authentication."))
146                            ("host" "#f"
147                             ("If given, only accept connections originating "
148                              "from this hostname/IP.  See " (tt "listen")
149                              " for more details."))
150                            ("backlog" "4"
151                             ("Maximum number of pending connections.  See "
152                              (tt "listen") " for more details."))
153                            ("timeout-read" "50000"
154                             ("Timeout in milliseconds before aborting a read "
155                              "operation.  NOTE: DO NOT SET THIS TO " (tt "#f")
156                              "!  Timeouts are handled gracefully and will not "
157                              "generate errors, and are required for proper "
158                              "operation."))
159                            ("timeout-write" "50000"
160                             ("Timeout in milliseconds before aborting a write "
161                              "operation.  NOTE: DO NOT SET THIS TO " (tt "#f")
162                              "!  Timeouts are handled gracefully and will not "
163                              "generate errors, and are required for proper "
164                              "operation."))
165                            ("timeout-accept" "50000"
166                             ("Timeout in milliseconds before aborting an "
167                              "accept operation.  NOTE: DO NOT SET THIS TO "
168                              (tt "#f") "!  Timeouts are handled gracefully "
169                              "and will not generate errors, and are required "
170                              "for proper operation."))
171                            ("reader" "read"
172                             ("Procedure to read from a session's input port."))
173                            ("evaler" "eval"
174                             ("Procedure for evaluating input in a session.  "
175                              "Takes TWO arguments, the expression to "
176                              "evaluate and the session object.  This allows "
177                              "the " (tt "rrepl-session:extra") " field to "
178                              "be used, if desired."))
179                            ("printer" "write + newline"
180                             ("Procedure for displaying evaluated output to "
181                              "a session's output port.  Takes two arguments, "
182                              "the object to be written and the output port.  "
183                              "NOTE: A NEWLINE MUST BE ADDED BY THIS PROCEDURE "
184                              "FOLLOWING OUTPUT."))
185                            ("close-in" "close-input-port"
186                             ("Procedure for closing a session's input port."))
187                            ("close-out" "close-output-port"
188                             ("Procedure for closing a session's output "
189                              "port."))))
190                    (procedure
191                        "(rrepl-server-close SERVER-OBJ)"
192                        (p "Closes the remote-repl server specified by "
193                           (tt "SERVER-OBJ") ".  This includes closing the "
194                           "listener port and all active sessions."))
195                )
196                (subsubsection "RREPL-SERVER Procedures"
197                    (group
198                        (procedure
199                            "(rrepl-server? OBJ)"
200                            (p "Returns " (tt "#t") " if " (tt "OBJ") " is a "
201                               (tt "rrepl-server") " object."))
202                        (procedure
203                            "(rrepl-server:close-listen SERVER-OBJ)"
204                            (p "Returns the procedure for closing the listener "
205                               "port.  This is a wrapper around the procedure "
206                               "specified by the keyword " (tt "clisten")
207                               " for condition safety and metadata cleanup."))
208                        (procedure
209                            "(rrepl-server:read SERVER-OBJ)"
210                            (p "Returns the procedure for reading from a "
211                               "session's input port, as specified by the "
212                               (tt "reader") " keyword."))
213                        (procedure
214                            "(rrepl-server:eval SERVER-OBJ)"
215                            (p "Returns the procedure for evaluating input "
216                               "in a session, as specified by the " 
217                               (tt "evaler") " keyword."))
218                        (procedure
219                            "(rrepl-server:print SERVER-OBJ)"
220                            (p "Returns the procedure for printing to a "
221                               "session's output port, as specified by the "
222                               (tt "printer") " keyword."))
223                        (procedure
224                            "(rrepl-server:close SERVER-OBJ)"
225                            (p "Returns a procedure that takes a "
226                               (tt "rrepl-server") " object and a "
227                               (tt "rrepl-session") " object, and shuts down "
228                               "the session, after closing the ports.  "
229                               "Uses the procedures specified by the "
230                               (tt "close-in") " and " (tt "close-out")
231                               " keywords."))
232                        (procedure
233                            "(rrepl-server:listener SERVER-OBJ)"
234                            (p "Returns the listener port associated with "
235                               (tt "SERVER-OBJ") ", or " (tt "#f") " if "
236                               "not accepting connections."))
237                        (procedure
238                            "(rrepl-server:listen-thr SERVER-OBJ)"
239                            (p "Returns " (tt "SERVER-OBJ") "'s listener "
240                               "thread."))
241                        (procedure
242                            "(rrepl-server:remotes SERVER-OBJ)"
243                            (p "Returns a list of currently active "
244                               (tt "rrepl-session") " objects connected to "
245                               (tt "SERVER-OBJ") "."))
246                        (procedure
247                            "(rrepl-server:accepting SERVER-OBJ)"
248                            (p "Returns " (tt "#t") " if " (tt "SERVER-OBJ")
249                               " is accepting new connections, or "
250                               (tt "#f") " otherwise."))
251                        (procedure
252                            "(rrepl-server:accepting! SERVER-OBJ BOOL)"
253                            (p "Sets the accepting-new-connections state of "
254                               (tt "SERVER-OBJ") " to " (tt "BOOL") ".  This "
255                               "is intended for use in " (tt "auth") " "
256                               "procedures to force the listener port to "
257                               "close after a certain number of connections.  "
258                               "Setting this to " (tt "#f") " will irrevocably "
259                               "kill the listener port."))
260                        (procedure
261                            "(rrepl-server:active SERVER-OBJ)"
262                            (p "Returns " (tt "#t") " if " (tt "SERVER-OBJ")
263                               " is currently active, or " (tt "#f") " if "
264                               "it is closed.  Note: A server running with "
265                               "a closed listener port is explicitly allowed."))
266                        (procedure
267                            "(rrepl-server:active! SERVER-OBJ BOOL)"
268                            (p "Sets the running state of " (tt "SERVER-OBJ")
269                               " to " (tt "BOOL") ".  This should generally "
270                               "never be used, as setting to " (tt "#f") 
271                               " will shut down the server without proper "
272                               "cleanup."))
273                    ))
274                (subsubsection "RREPL-SESSION Procedures"
275                    (group
276                        (procedure
277                            "(rrepl-session? OBJ)"
278                            (p "Returns " (tt "#t") " if " (tt "OBJ") " is a "
279                               (tt "rrepl-session") " object."))
280                        (procedure
281                            "(rrepl-session:inport SESSION-OBJ)"
282                            (p "Returns the input socket port associated with "
283                               (tt "SESSION-OBJ") "."))
284                        (procedure
285                            "(rrepl-session:outport SESSION-OBJ)"
286                            (p "Returns the output socket port associated with "
287                               (tt "SESSION-OBJ") "."))
288                        (procedure
289                            "(rrepl-session:thread SESSION-OBJ)"
290                            (p "Returns " (tt "SESSION-OBJ") "'s REPL thread."))
291                        (procedure
292                            "(rrepl-session:extra SESSION-OBJ)"
293                            (p "Returns " (tt "SESSION-OBJ") "'s \"extra\" "
294                               "object (initially " (tt "#f") ").  This is an "
295                               "arbitrary user-settable object for augmenting "
296                               "any other functionality."))
297                        (procedure
298                            "(rrepl-session:extra! SESSION-OBJ OBJ)"
299                            (p "Sets the \"extra\" object for "
300                               (tt "SESSION-OBJ") " to " (tt "OBJ") ".  "
301                               (tt "OBJ") " may be any object."))
302                        (procedure
303                            "(rrepl-session:active SESSION-OBJ)"
304                            (p "Returns " (tt "#t") " if session is open and "
305                               "active, or " (tt "#f") " otherwise."))
306                        (procedure
307                            "(rrepl-session:active! SESSION-OBJECT BOOL)"
308                            (p "Sets the running state of " (tt "SESSION-OBJ")
309                               " to " (tt "BOOL") ".  This should generally "
310                               "never be used, as setting to " (tt "#f") 
311                               " will end the session without proper cleanup."))
312                    )))
313
314            (subsection "Client Procedures"
315                (p "For the client component, use: "
316                   (tt "(require-extension remote-repl-client)"))
317                (group
318                    (procedure
319                        "(rrepl-client-connect HOSTNAME PORTNUM [KEYARGS...])"
320                        (p "Creates a new remote-repl client and returns a "
321                           (tt "rrepl-client") " object.  The server "
322                           "automatically connects and authenticates to "
323                           (tt "HOSTNAME") " on port " (tt "PORTNUM") ".  "
324                           (tt "KEYARGS") " are optional keyword arguments "
325                           "for extending/tuning the client's behaviour, as "
326                           "given below:")
327                        (table-spec
328                            (tt tt p)
329                            ("Keyword" "Default" "Description")
330                            ("connect" "tcp-connect"
331                             ("Procedure to create a socket connection to "
332                              "a remote host.  Must take the hostname and "
333                              "portnum as its arguments, and returns an "
334                              "input port and an output port."))
335                            ("auth" "identity"
336                             ("After connecting with " (tt "connect") ", "
337                              "the " (tt "auth") " procedure is evaluated on "
338                              "a new " (tt "rrepl-client") " object to "
339                              "perform any authentication steps before handing "
340                              "off to the user.  Returns the "
341                              (tt "rrepl-client") " object on success, or "
342                              (tt "#f") " on failure."))
343                            ("reader" "read-line"
344                             ("Procedure to read the output (one line) from "
345                              "the remote REPL."))
346                            ("printer" "write + newline"
347                             ("Procedure for sending expressions to the "
348                              "output port for evaluation by the remote REPL.  "
349                              "Takes two arguments, the expression to be "
350                              "run and the output port.  "
351                              "NOTE: A NEWLINE MUST BE ADDED BY THIS PROCEDURE "
352                              "FOLLOWING OUTPUT."))
353                            ("close-in" "close-input-port"
354                             ("Procedure for closing a client's input port."))
355                            ("close-out" "close-output-port"
356                             ("Procedure for closing a client's output "
357                              "port."))))
358                    (procedure
359                        "(rrepl-client-send CLIENT-OBJ EXPRESSION)"
360                        (p "Sends " (tt "EXPRESSION") " to the remote REPL "
361                           "for evaluation, and returns the result as a "
362                           "string."))
363                    (procedure
364                        "(rrepl-client-close CLIENT-OBJ)"
365                        (p "Closes the remote REPL client specified by "
366                           (tt "CLIENT-OBJ") ".  This includes closing the "
367                           "ports and notifying the server that the session "
368                           "is over."))
369                )
370                (subsubsection "RREPL-CLIENT Procedures"
371                    (group
372                        (procedure
373                            "(rrepl-client? OBJ)"
374                            (p "Returns " (tt "#t") " if " (tt "OBJ") " is a "
375                               (tt "rrepl-client") " object."))
376                        (procedure
377                            "(rrepl-client:read CLIENT-OBJ)"
378                            (p "Returns the procedure for reading from a "
379                               "client's input port, as specified by the "
380                               (tt "reader") " keyword."))
381                        (procedure
382                            "(rrepl-client:print CLIENT-OBJ)"
383                            (p "Returns the procedure for printing to a "
384                               "client's output port, as specified by the "
385                               (tt "printer") " keyword."))
386                        (procedure
387                            "(rrepl-client:close CLIENT-OBJ)"
388                            (p "Returns a procedure that takes a "
389                               (tt "rrepl-client") " object, and shuts down "
390                               "the client, after closing the ports.  "
391                               "Uses the procedures specified by the "
392                               (tt "close-in") " and " (tt "close-out")
393                               " keywords."))
394                        (procedure
395                            "(rrepl-client:inport CLIENT-OBJ)"
396                            (p "Returns the input socket port associated with "
397                               (tt "CLIENT-OBJ") "."))
398                        (procedure
399                            "(rrepl-client:outport CLIENT-OBJ)"
400                            (p "Returns the output socket port associated with "
401                               (tt "CLIENT-OBJ") "."))
402                        (procedure
403                            "(rrepl-client:active CLIENT-OBJ)"
404                            (p "Returns " (tt "#t") " if client is connected "
405                               "and active, or " (tt "#f") " otherwise."))
406                    )))
407
408            (subsection "Bugs"
409                (p "None known"))
410
411            (subsection "Licence"
412                (pre ,(read-all "remote-repl/LICENCE")))
413        ))))
414
415
416(eggdoc->html doc (elf-eggdoc-ss doc))
Note: See TracBrowser for help on using the repository browser.