;;; spiffy-utils-eggdoc.scm (use eggdoc) (define license "Copyright (c) 2004 - 2006, Peter Bex (peter.bex@xs4all.nl) All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of author nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.") (define example '((pre #<number 0)) (boolean . ,(get-var 'boolean string->bool)) (string . ,(get-var 'string identity "")))) (define (addfoo var) (string-append var "foo ")) (define (delfoo var) (string-substitute "foo " "" var)) (define (alist-replace var func) (alist-cons var (func (alist-ref var vars)) (alist-delete var vars))) (define my-rules `((url *macro* . ,(lambda (url target text) `(a (@ href ,target) ,text))))) (define document `((html (head (title "GET-var and typing showcase")) (body (dl (dt "Integer:") (dd (url ,(link-to "test.ssp" (alist-replace 'integer sub1)) "sub1") " " ,(alist-ref 'integer vars) " " (url ,(link-to "test.ssp" (alist-replace 'integer add1)) "add1")) (dt "Boolean:") (dd ,(->string (alist-ref 'boolean vars)) " " (url ,(link-to "test.ssp" (alist-replace 'boolean not)) "Toggle")) (dt "String:") (dd (url ,(link-to "test.ssp" (alist-replace 'string delfoo)) "Delete foo") " " ,(alist-ref 'string vars) (url ,(link-to "test.ssp" (alist-replace 'string addfoo)) "Add foo"))))))) (SRV:send-reply (pre-post-order document (append my-rules universal-conversion-rules))) EOF ))) (define doc `((eggdoc:begin (name "spiffy-utils") (description "Utility library for the spiffy webserver") (author (url "mailto:peter.bex@xs4all.nl" "Peter Bex")) (history (version "0.4" "Add " (code "link-to") " function for constructing" " URL with GET parameters. Add default and " "string-conversion optional arguments to variable-getters." " Remove " (code "assocval") " as it is equivalent to " (code "alist-ref") ".") (version "0.3" "Removed runtime-dependency on " (code "match-support") " unit [Felix].") (version "0.2" "Fixed cookie quoting bug [Thanks to Michele Simionato].") (version "0.1" "Initial version.")) (requires (url "spiffy.html" "spiffy") (url "url.html" "url")) (usage) (documentation (p "Utility library for spiffy to make advanced webprogramming " "more comfortable. Features include:") (ul (li (url "ftp://ftp.rfc-editor.org/in-notes/rfc2109.txt" "RFC 2109") " cookies.") (li "Easy accessor functions for GET-, POST- and cookie variables.") (li "Easy construction of URLs with GET-arguments.")) (procedure "(link-to url variable-alist)" "Construct an URL string that links to " (code "url") " and has an association list of variable/value pairs. " "These pairs can be extracted from the request arguments " "using " (code "get-var") ". Both the name and the " "value objects of the alist are converted to strings " "using " (code "->string") ".") (procedure "(get-var varname [string->type] [default])" "Returns the value for the named variable from the GET " "argument list, or " (code "default") " if it could not " "be found. (" (code "#f") " if not specified). The " "returned value is a string which can optionally be " "converted to the desired type by supplying a " (code "string->type") " argument.") (procedure "(post-var varname [string->type] [default])" "Same as " (code "get-var") ", but for http POST request" "variables instead.") (procedure "(cookie-var varname [string->type] [default])" "Same as " (code "get-var") ", but for cookie variables " "instead. Cookies automatically get sent by the user " "agent on each request, both GET and POST, so they're " "always available.") (procedure "(string->bool b)" "Convenience function to convert the " (code "string") " value " (code "b") " to a " (code "") "value. " "(useful in combination with " (code "get-var") ", " (code "post-var") " and " (code "cookie-var") ".") (procedure "(string->boolean b)" "An alias for " (code "string->bool")) (procedure "(write-cookie name value [comment] [max-age] [domain] [path] [secure]" "Instruct Spiffy to write a cookie header in the current " "reply. Cookies are " (code "name/value") " pairs of " "strings (but any value is ok; " (code "->string") " is " "automatically called on the two values). A cookie has an " "optional comment string for the user if he has a client " "which allows him to view the cookies. Cookies will expire " "when the session ends (usually when the browser closes) " "unless the " (code "max-age") " is supplied, which is an " "integer argument declaring the maximum time the cookie " "can be stored on the client side, in seconds. The domain " "string specifies for which domain the cookie is. The " "cookie will only be returned on subsequent requests to " "that domain. By default, the domain is the domain from " "which the cookie originates. The path string specifies " "the topmost path from which this cookie is active. " "If there are multiple cookies with the same name, the " "value from the cookie with the least generic " "(\"deepest\") path will be passed to the server. " "Finally, the boolean secure can be set to " (code "#t") " if the cookie should be treated as confidential " "information. If the user wishes to set one parameter, " "but not any other optional parameters, the value " (code "#f") " can be used. These parameters will be " "ignored.") (procedure "(delete-cookie name [domain] [path]" "Instruct Spiffy to write a cookie header constructed in " "such a way that the cookie with the supplied " (code "name") " (also converted to a string with " (code "->string") ") will be deleted. The two optional " "parameters behave as with " (code "write-cookie") ". (See " "above.)") (procedure "(exec cmd [disp])" "Execute the commandline indicated by the " (code "cmd") " string and give its standard output as a string result." " The optional " (code "disp") " argument will be used " " to display each line, so one can add HTML tags to every " " line of output if so desired. This allows one to write " " simple one-liners like:" (code "Uptime: ") (strong "Warning:") " this function passes the commandline " "right to the shell, so never build it from user input.")) (examples ,example) (license ,license)))) (eggdoc->html doc)