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 HTML tags as Scheme procedures is regarding to 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 no 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://chicken.wiki.br/spiffy#web-scheme-handler for further details).

Requirements

Procedures, macros and parameters

General

ws:page

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 an alist. Each element from the alist is a table row. 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

an 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

an 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 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 format-lines 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 strings. 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 strings. 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://galinha.ucpel.tche.br/web-scheme/web-scheme.png is used.

Accents -> HTML entities translation

ws:use-entities-translation

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

Translate special symbols into HTML entities (e.g., á becomes &aacute;). 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.

ws:post-vars

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.

Examples

License

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.