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

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

fixes and version bump

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