source: project/release/3/remote-repl/tags/1.1.3/doc.scm @ 11675

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

release tag 1.1.3

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