Changeset 12521 in project


Ignore:
Timestamp:
11/15/08 18:48:00 (11 years ago)
Author:
sjamaan
Message:

Document the spiffy modules now that they've been ported

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/spiffy

    r12514 r12521  
    252252request was just parsed. The argument is the new request to use.
    253253Be careful, this makes it very easy to introduce unwanted endless loops!
     254
     255=== Modules
     256
     257This section will describe what the various modules that come with
     258Spiffy are and how they work.
     259
     260==== ssp-handler
     261
     262SSP, or Scheme Server Pages, are a way to embed Scheme in HTML
     263pages. Files with an extension of {{.ssp}} are handled specifically,
     264by replacing occurrences of certain reserved tags with Scheme code.
     265There are two possible forms, either the long version, where all
     266output is redirected to the HTTP response port, or the short, where
     267the result of the embedded expression is displayed in the response.
     268The tags default to {{<?scheme}} and {{<?}}, see Configuration for how
     269to change them.
     270
     271<enscript highlight=scheme>
     272   <html><body>
     273   <ol><?scheme (for-each (lambda (i) (printf "<li>~S~%" i)) (iota 5))?></ol>
     274   <br />
     275   <b><?(call-with-values (lambda () (user-information (current-user-id))) (lambda (name . _) name))?><b>
     276   </body></html>
     277</enscript>
     278
     279would generate for example something like this:
     280
     281     1. 0
     282     2. 1
     283     3. 2
     284     4. 3
     285     5. 4
     286
     287  (felix x 500 100 /home/felix /bin/bash)
     288
     289When a {{.ssp}} file is loaded the first time, or when it has been
     290modified, then a translation takes place that generates a loadable
     291Scheme source file (with the extension {{.sspx}}, in the same
     292directory as the original file) from the original data, so in the
     293above example something like this would be generated:
     294
     295<enscript highlight=scheme>
     296  (let ()
     297    (display "<html><body>\n<ol>")
     298    (for-each (lambda (i) (printf "<li>~S~%" i)) (iota 5))
     299    (display "</ol>\n<br />\n<b>")
     300    (display (call-with-values (lambda () (user-information (current-user-id))) (lambda (name . _) name)))
     301    (display "<b>\n</body></html>\n") )
     302</enscript>
     303
     304Note that the body is evaluated in a {{(let () ...)}} form.
     305
     306Note: each request runs in a separate thread, so code in {{.ssp}}
     307pages should take care when using global variables.
     308
     309===== Configuration
     310
     311The SSP handler can be configured with the following options:
     312
     313<parameter>(ssp-short-open-tag [tag-regexp])</parameter>
     314
     315The opening tag for short fragments. Default: {{<?}}
     316
     317<parameter>(ssp-long-open-tag [tag-regexp])</parameter>
     318
     319The opening tag for long fragments. Default: {{<?scheme}}
     320
     321<parameter>(ssp-close-tag [tag-regexp])</parameter>
     322
     323The closing tag for Scheme fragments in {{.ssp}} files. Default: {{?>}}
     324
     325<parameter>(ssp-eval-environment [environment])</parameter>
     326
     327The environment passed to {{eval}} when evaluating Scheme code inside
     328{{.ssp}}-pages.  Default: {{interaction-environment}}
     329
     330===== Runtime information
     331
     332For the duration of evaluating a SSP page, the following parameters
     333will have a value assigned to them:
     334
     335<parameter>(current-workdir [path])</parameter>
     336
     337During execution, the current working directory of the SSP handler.
     338Any of the "include" procedures (ssp-include, ssp-stringize) will
     339interpret their file arguments to be relative to this directory.
     340
     341<parameter>(exit-handler [handler])</parameter>
     342
     343During execution of an ssp page, {{exit-handler}} is bound to a
     344procedure that will finish the current page, ignoring any further
     345content or code.
     346
     347===== Procedures
     348
     349The ssp-handler module adds the following procedures to the environment:
     350
     351<procedure>(ssp-handler filename)</procedure>
     352
     353The handler itself, which should be used in the {{file-extension-handlers}}
     354parameter list.
     355
     356<procedure>(ssp-include filename)</procedure>
     357
     358Translates the file {{filename}} into Scheme by replacing {{<?scheme ... ?>}}
     359and {{<? ... ?>}} sequences (if needed) and writes the translated contents
     360to the current output-port.
     361
     362<procedure>(ssp-stringize FILENAME)</procedure>
     363
     364Similar to {{ssp-include}}, but instead of writing the translated
     365text, the text is returned as a string.
     366
     367==== web-scheme-handler
     368
     369Another way of executing Scheme code to produce content are {{.ws}}
     370files: these should contain a Scheme expression that is expected to
     371evaluate to a string which will be directly written as the response to
     372the current request. This facility is intended for Scheme code that
     373uses the [[web-scheme]] extension.
     374
     375You can use the {{web-scheme-handler}} for any Scheme file which
     376returns HTML as a string or which has a side-effect of outputting the
     377HTML. If it's the latter, make sure the final statement in your file
     378does not return a string or it will be appended to the output (just
     379like in the {{csi}} REPL).
     380
     381'''Tip''' This handler type is perfect not only for web-scheme but
     382also for when you're using {{SRV:send-reply}} with SXML or for example a
     383wiki-to-string translator.
     384
     385Note: each request runs in a separate thread, so code in {{.ws}} pages
     386should take care when using global variables.
     387
     388Note: web-scheme-handler is a separate extension and must be imported
     389as such.
     390
     391<enscript highlight=scheme>
     392(require-extension web-scheme-handler)
     393</enscript>
     394
     395===== Configuration
     396
     397The Web-scheme handler can be configured with the following options:
     398
     399<parameter>(web-scheme-eval-environment [environment])</parameter>
     400
     401The environment passed to {{eval}} when evaluating Scheme code inside
     402{{.ws}}-pages.  Default: {{interaction-environment}}
     403
     404===== Procedures
     405
     406The Web-scheme handler adds only one procedure to the environment:
     407
     408<procedure>(web-scheme-handler filename)</procedure>
     409
     410The handler itself, which should be used in the {{file-extension-handlers}}
     411parameter list.
     412
     413
     414==== cgi-handler
     415
     416Spiffy supports [[http://www.ietf.org/rfc/rfc3875|CGI/1.1 as specified by RFC 3875]].
     417
     418All request headers will be passed as environment variables to the CGI
     419program, prefixed with {{"HTTP_"}}, and converted to uppercase, with
     420hyphens ("-") replaced by an underscore ("_"). The CGI program will
     421receive the request body in unparsed form from stdin and should write
     422a complete HTTP response to stdout.  Any headers that are missing but
     423required for HTTP will be added by Spiffy.  For more info on how a CGI
     424script is called, consult the spec.
     425
     426The {{AUTH_TYPE}} and {{REMOTE_USER}} environment variables are
     427currently not set during invocation of CGI subprocesses.
     428The {{REMOTE_IDENT}} environment variable is not and never will be supported.
     429
     430===== Configuration
     431
     432CGI handler can be configured with the following parameters:
     433
     434<procedure>(cgi-default-environment [env-alist])</procedure>
     435
     436The environment variables that should be in the default environnment
     437of every CGI program.  Variables like {{SCRIPT_NAME}} will be added
     438dynamically to the end of this alist.
     439
     440Default:
     441<enscript highlight=scheme>
     442(("SERVER_SOFTWARE" . ,(server-software))
     443 ("GATEWAY_INTERFACE" . "CGI/1.1")
     444 ("REDIRECT_STATUS" . "200"))
     445</enscript>
     446
     447===== Procedures
     448
     449CGI-handler adds two procedures to the environment:
     450
     451<procedure>(cgi-handler filename [interpreter])</procedure>
     452
     453The {{cgi-handler}} procedure is called by {{cgi-handler*}} with the
     454filename. It's not very useful on its own.
     455
     456<procedure>(cgi-handler* [interpreter])</procedure>
     457
     458The {{cgi-handler*}} procedure is usually more useful.  It allows you
     459to define an interpreter to use for files and returns a file handler.
     460See the example above for {{file-extension-handlers}}.
     461
     462
     463==== simple-directory-handler
     464
     465In order to get directory listings, you can use
     466{{simple-directory-handler}}.  Just assign the
     467{{simple-directory-handler}} to {{handle-directory}} and you're set.
     468
     469===== Configuration
     470
     471The simple directory handler has a few configuration options:
     472
     473<procedure>(simple-directory-dotfiles? [dotfiles?])</procedure>
     474
     475Determines if dotfiles should show up in the directory listings.
     476Default: {{#f}}
     477
     478<procedure>(simple-directory-display-file [displayer])</procedure>
     479
     480A lambda that accepts three arguments: the remote filename, the local
     481filename and a boolean that says if the file is a directory.  This
     482lambda should output a table row with the desired information.
     483Defaults to a lambda that prints the name, size and date when the file
     484was last modified.
     485
     486===== Procedures
     487
     488The simple-directory handler adds only one procedure to the environment:
     489
     490<procedure>(simple-directory-handler pathname)</procedure>
     491
     492The handler itself, which should be used in the {{handle-directory}}
     493parameter.
     494
    254495
    255496=== Changelog
Note: See TracChangeset for help on using the changeset viewer.