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

Last change on this file since 11670 was 11670, checked in by elf, 13 years ago

fix for documentation building

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