Outdated egg!

This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for the CHICKEN 4 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

Introduction

Web-scheme is a Chicken Scheme extension which implements a web programming language based on Scheme. It can be used with the spiffy web server to generate programmable dynamic web pages.

Web-scheme basically implements all HTML tags as Scheme procedures (see note below), so you can format your pages just like you'd do with HTML, but using the Scheme syntax and having the possibility of using the Chicken Scheme's features for programming. Additionaly, it provides some (hopefuly) useful procedures and macros to ease the formatting of web pages. A special case regarding to HTML tags as Scheme procedures is HTML attributes which don't take a value, e.g., the multiple attribute, which can be used, for exemple, in the <select> tag. In this special case, web-scheme requires a boolean (usually #t) as a value to the attribute.

The procedures defined by web-scheme to generate HTML tags are named according to tag names. So, the procedure which generates the blockquote tag is called blockquote. There are exceptions, however: ws:select and ws:map not to clash with common Scheme names.

You can either use web-scheme as a programming language for generating dynamic web pages with spiffy or for generating static HTML pages which can be used with any other web server.

From version 1.50, spiffy interprets files with .ws suffix as web-scheme files. So, to make dynamic web pages with web-scheme, just use it as if you were making a regular Scheme program. From version 3.0, spiffy uses web-scheme as a special handler (see http://wiki.call-cc.org/spiffy#web-scheme-handler for further details).

The Emacs-Lisp file web-scheme.el provides a few helpful commands to simplify escaping quotes and slashes (i.e., inside pre tags).

Besides providing HTML tags as procedures, web-scheme provides the procedures, macros, variables and parameters you can see on the next section.

Author

Mario Domenech Goulart

Requirements

spiffy, doctype

Procedures, macros and parameters

General

ws:page

   '''procedure:''' (ws:page CONTENTS #!key ADDITIONAL-HEADERS PAGE-TITLE DOCTYPE CSS-FILE CHARSET BODY-ATTRIBS)

Creates an HTML page containing CONTENTS (a string). Keywords arguments may be used to customize the page.

ADDITIONAL-HEADERS is a string containg additional headers to be inserted in the (header ...) tag (default = "").

PAGE-TITLE is the title of the generated page (to be used in the (title ...)) tag (default = "").

CSS-FILE may be either a path to a Cascading Style Sheet file, to be linked fom the generated page (the default value is #f, so no CSS is used) or a list of paths to CSS files. If a list of paths is used, the elements which are also lists are read and inlined into the generated page. Example: css-file: '("css1.css" ("css2.css")). In the example, css1.css would be linked from the generated page (using the link tag) and css2.css would be inlined into the generated page (e.g., web-scheme would read the css2.css file and inline its contents in the HTML code).

DOCTYPE specifies the document type of the generated page. The default value is doctype:html-4.01-strict. The possible values are the ones available from the doctype egg.

CHARSET specifies the default charset to be used in the corresponding meta tag of the document. The default value is iso-8859-1.

BODY-ATTRIBS is a list of attributes and their values to be used in the body tag.

ws:make-table

  '''procedure:''' (ws:make-table TABLE . ARGS)

Creates an HTML table. TABLE is a list of lists. Each sub-list element from TABLE is representative of a table row, with the requirement that each row element have a string representation when ->string is automatically applied to it. ARGS are keyword arguments. ws:make-table understands the following arguments:

row-attribs: a list of row attributes (e.g., '(bgcolor "yellow" align "center")).
cell-attribs: a list of cell attributes (e.g., '(width "30" valign "middle")).
line-attribs: a one-argument procedure which takes a line number (corresponding to the current table row being processed) and returns a list of row attributes.
line-format: a one-argument procedure which takes a line number (corresponding to the current table row being processed) and returns a procedure to be applied to all cells of the nth table line (where n is the line number used as an argument for the given procedure).

ws:table-colorizer

  '''procedure:''' (ws:table-colorizer ID-EVEN ID-ODD)

Returns a procedure to colorize table lines. To be used by the line-format keyword argument of ws:make-table. ID-EVEN and ID-ODD are values for the id attribute of div tags used to format the lines.

ws:itemize

   '''procedure:''' (ws:itemize ITEMS . ARGS)

Creates an unordered list of ITEMS. ITEMS is a list of items having a string representation (->string is applied). ARGS are keyword arguments. ws:itemize understands the following arguments:

list-attribs: a list of attributes for the list of items (e.g., '(type "circle")).
items-attribs: a list of attributes for each item from the list.

ws:enumerate

   '''procedure:''' (ws:enumerate ITEMS . ARGS)

Creates an ordered list of ITEMS. ITEMS is a list of items having a string representation (->string is applied). ARGS are keyword arguments. ws:enumerate understands the following arguments:

list-attribs: a list of attributes for the list of items (e.g., '(type "circle")).
items-attribs: a list of attributes for each item from the list.

ws:mailto

   '''procedure:''' (ws:mailto ADDRESS #!optional OBFUSCATION-FUNCTION)

Creates a link to an e-mail address ADDRESS. The optional parameter OBFUSCATION-FUNCTION is a one-argument procedure which formats the e-mail address in order to obfuscate it (against spam).

The following obfuscation functions are available:

ws:email-at-dot-obfuscation: transforms user@address.somewhere into user at address dot somewhere.
ws:email-paren-uline-obfuscation: transforms user@address.somewhere into user()address_somewhere.

ws:blank

   '''variable: ''' ws:blank

Produces an HTML whitespace.

ws:vspace

   '''procedure:''' (ws:vspace #!optional UNITS)

Generates an HTML vertical space by creating empty paragraphs. UNITS determines the length of the space.

ws:hspace

   '''procedure:''' (ws:hspace #!optional UNITS)

Generates an HTML horizontal space by inserting whitespaces. UNITS determines the length of the space.

ws:load

   '''procedure:''' (ws:load FILE)

Loads FILE. FILE can be a path relative to the current working directory (uses spiffy's (current-workdir and load).

ws:text-only-made-with

   '''procedure:''' (ws:text-only-made-with)

Generates a text only made with web-scheme logo.

ws:made-with

   '''procedure:''' (ws:made-with #!optional logo)

Generates a graphical made with web-scheme logo. if LOGO (an image file) is not provided, the one at http://wiki.call-cc.org/web-scheme-data/web-scheme.png is used.

ws:check-html-syntax

   '''parameter:''' ws:check-html-syntax

If set to #t web-scheme checks if the attributes used for HTML tags are ok and generates a commented warning on the HTML page. Default is #f.

ws:human-readable-html

   '''parameter:''' ws:human-readable-html

If set to #t, web-scheme produces HTML code which is (hopefully) readable by humans. If #f, no effort is made to generate human-readable HTML. Default is #t.

Accents -> HTML entities translation

ws:use-entities-translation

   '''parameter:''' ws:use-entities-translation

Translate special symbols into HTML entities (e.g., á becomes á). If no argument is provided, no translation is performed. Currently translation is only available for iso-8859-1 symbols (e.g., (ws:use-entities-translation 'iso-8859-1)).

ws:iso-8859-1->html-entities

   '''procedure:''' (ws:iso-8859-1->html-entities text)

Converts iso-8859-1 text TEXT to HTML entities.

GET and POST variables

ws:with-get-vars

   '''macro:''' (ws:with-get-vars VARLIST BODY)

Binds all the HTTP GET method's variables listed in VARLIST to Scheme variables. If a listed variable is not available from the GET method, it's bound to #f in Scheme.

Example:

   (define (beavis&butthead)
     (ws:with-get-vars (beavis butthead)
       (ws:itemize
        (list
         (or beavis "no beavis")
         (or butthead "no butthead")))))

ws:post-vars

   '''macro:''' (ws:with-post-vars VARLIST BODY)

The same as ws:with-get-vars, but for HTTP POST method variables.

ws:with-post/get-vars

   '''macro:''' (ws:with-post/get-vars VARLIST BODY)

The same as ws:with-get-vars and ws:with-get-vars, but first try to bind HTTP POST method variables, then GET.

ws:http-vars

   '''variable:''' ws:http-vars

Variable which is bound to the list of the variables names (as strings) from the latest invocation of ws:with-post-vars or ws:with-get-vars. It's convenient to use with post-var and get-var from the spiffy-utils extension.

Example:

   (ws:with-post-vars (name address city)
       (ws:make-table (map (lambda (var)
                              (list var (post-var var)))
                           ws:http-vars)))

Debugging

ws:debug-file

   '''parameter:''' ws:debug-file

A parameter which indicates the file where debugging messages are written. #f (default) means no debugging.

ws:debug

   '''procedure:''' (ws:debug . msgs)

Write debugging information (MSGS) to the file configured by the ws:debug-file parameter.

Examples

http://schemers.ucpel.tche.br/mario/examples

License

This software is licensed under the BSD license.

Copyright (c) 2005, 2006, 2007 Mario Domenech Goulart.  All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the Software),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Version history

0.84: Fix for the embed tag, added noembed tag.
0.83: Support for tags: tbody, tfoot and embed
0.82: Explict use of srfi-69 (Thanks to Kon Lovett).
0.81: Fix for ws:-prefixed procedures.
0.8: ws:select instead of select to avoid name clash with chicken's select macro, wiki documentation, ws:debug, ws:debug-file, ws:human-readable-html
0.7: Added ws:table-colorizer and ws:iso-8859-1->html-entities, fix for the comment procedure.
0.6: css-file keyword argument for ws:page accepts a list of filenames, syntax for inlining CSS code in HTML pages (ws:page), body-attribs and charset keyword arguments (ws:page), fix for the meta tag, added ws:with-post/get-vars macro.
0.5: Nested scheme lists now produce nested HTML lists (ws:itemize and ws:enumerate), new tags and attributes, line-breaking fixing for some tags, added support for HTML attributes without value, better iso-8859-1 entities translation support, new procedures: ws:page and ws:load, several bugfixes.
0.4.0: Several changes (some backwards incompatible), code cleanup, better documentation, macros to bind GET and POST HTTP methods variables to Scheme variables, improved support for HTML tags
0.3.5: Support for link and a small addition to meta tags by Peter Busser
0.3.4: Added version and docs to setup script
0.3.3: Initial release as an egg