@c =================================================================== @c
@c    serrano/prgm/project/bigloo/manuals/text.texi                    @c
@c    ------------------------------------------------------------     @c
@c    Author      :  Joseph Donaldson                                  @c
@c    Creation    :  Tue Aug 31 13:16:21 2010                          @c
@c    Last change :                                                    @c
@c    Copyright   :  2010 Manuel Serrano                               @c
@c    ------------------------------------------------------------     @c
@c    Web Programming Tools                                            @c
@c =================================================================== @c

@c ------------------------------------------------------------------- @c
@c    web ...                                                          @c
@c ------------------------------------------------------------------- @c
@node Web, CSV, Eval, Top
@comment  node-name,  next,  previous,  up
@chapter Web
@cindex Web

This chapter describes the Bigloo API for Web programming.

@comment node-name, next,          previous, up
@menu
* Web Overview::    What is this Bigloo web library?.
* XML::             XML parsers, encoders, decoders.
* WebDAV::          WebDAV tools.
* CSS::             CSS parsers.
* Web Date::        Dates.
* JSON::            JSON parser.
@end menu

@node Web Overview, XML, , Web
@comment node-name, next, previous, up
@section Overview

The Bigloo web library supports tools helping Web programming.
It contains XML, JSON, and CSS parsers, WebDAV tools, and function
for handling the web formats of dates.

@node XML, WebDAV, Web Overview, Web
@comment node-name, next, previous, up
@section XML

@deffn {bigloo procedure} xml-parse input-port #!key (content-length 0) (make-element (lambda (tag attr body start-pos) (list tag attr body))) (make-comment (lambda (str pos) str)) (make-declaration (lambda (str pos) (cons 'declaration str))) (make-cdata (lambda (str pos) (cons 'cdata str))) (make-xml-declaration (lambda (attr pos) (cons 'xml-decl attr))) (make-instruction (lambda (str pos) (cons 'instruction str))) (specials '()) (strict #t) (encoding 'UTF-8) (eoi #f)
Parses an XML documention. The arguments are:

@itemize @bullet
@item @var{input-port} the input port containing the document to be parsed.
@item @var{content-length} if > 0, the number of characters to parse. 
@item @var{procedure} element constructor for backward compatibility.
A function of 3 arguments: tag, attributes, children.
@item @var{make-element} the element constructor.
A function of 4 arguments: tag, attributes, children, start position.
@item @var{make-comment} the comment constructor.
A function of 2 arguments: the comment and the start position.
@item @var{make-declaration} the declaration constructor.
A function of 2 arguments: the declaration and the start position.
@item @var{make-cdata} the cdata constructor.
A function of 2 arguments: the cdata and the start position.
@item @var{make-xml-declaration} the xml declaration constructor.
A function of 2 arguments: the xml-declaration and the start position.
@item @var{make-instruction} the instruction constructor.
A function of 2 arguments: the instruction and the start position.
@item @var{specials} an alist @code{(tag . parse)} of tags to be parsed
 using special parsers. This can be used to parse elements (e.g., HTML elements)
 that do not comply with strict syntax, for instance because they do not
 accept closing tags.
@item @var{strict} a boolean, require strict xml syntax conformance.
@item @var{encoding} a string, characters encoding.
@item @var{eoi} an optional predicat that is true on end-of-input.
@end itemize

@end deffn

@deffn {bigloo procedure} html-parse input-port #!key (content-length 0) (procedure list) (encoding 'UTF-8) (eoi #f)
Parse an HTML document. The optional arguments are:

@itemize @bullet
@item @var{input-port} the input port containing the document to be parsed.
@item @var{content-length} if > 0, the number of characters to parse.
@item @var{procedure} the function invoked to construct elements.
@item @var{encoding} characters encoding.
@item @var{eoi} an optional predicat that is true on end-of-input.
@end itemize

This function is mere wrapper of @code{xml-parse}.
@end deffn

@deffn {bigloo procedure} unhtml-port input-port output-port #!key table
Removes tags from @var{input-port} and write the result to @var{output-port}.
If provided, @var{table} must a hashtable associating HTML escape
sequences (e.g., "&amp;") to strings used in the replacement.
@end deffn

@deffn {bigloo procedure} unhtml str::bstring #!optional table
Removes HTML tags from the string @var{str}.
@end deffn

@deffn {bigloo procedure} xml-string-decode str
@deffnx {bigloo procedure} xml-string-decode! str
@deffnx {bigloo procedure} xml-string-encode str
Decode/encode XML strings.

@smalllisp 
(xml-string-decode "foo&gt;bar&#032;gee") @result{}  "foo>bar gee"
@end smalllisp
@end deffn

@deffn {bigloo procedure} html-string-decode str
@deffnx {bigloo procedure} html-string-encode str
Decode/encode HTML strings.

@smalllisp 
(xml-string-decode "foo&amp;bar&#quot;gee") @result{}  "foo&bar\"gee"
@end smalllisp
@end deffn

@node WebDAV, CSS, Web Date, Web
@comment node-name, next, previous, up
@section WebDAV

This section describes the functions that may help implementing WebDAV
servers and clients.

@deffn {class} &webdav-access-control-exception::&access-control-exception

The class used to raised access denied. It contains one field:

@itemize @bullet
@item @var{header}
@end itemize
@end deffn

@deffn {bigloo procedure} webdav-directory->list url #!key (timeout 0) (proxy #f)
@deffnx {bigloo procedure} webdav-directory->path-list url #!key (timeout 0) (proxy #f)
The list of files, respec. urls, in the directory @var{url}.
@end deffn

@deffn {bigloo procedure} webdav-directory->prop-list url #!key (timeout 0) (proxy #f)
The list of properties of a WebDAV repository.
@end deffn

@deffn {bigloo procedure} webdav-file-exists? url #!key (timeout 0) (proxy #f)
Return @code{#t} if and only if @var{url} exists, returns @code{#f} otherwise.
@end deffn

@deffn {bigloo procedure} webdav-directory? url #!key (timeout 0) (proxy #f) 
Return @code{#t} if and only if @var{url} is a directory, returns @code{#f} otherwise.
@end deffn

@deffn {bigloo procedure} webdav-file-modification-time url #!key (timeout 0) (proxy #f)
The last modification time of @var{url}.
@end deffn

@deffn {bigloo procedure} webdav-file-size url #!key (timeout 0) (proxy #f)
The file size.
@end deffn

@deffn {bigloo procedure} webdav-delete-file url #!key (timeout 0) (proxy #f)
@deffnx {bigloo procedure} webdav-delete-directory url #!key (timeout 0) (proxy #f)
Delete a file, respec. a directory.
@end deffn

@deffn {bigloo procedure} webdav-make-directory url #!key (timeout 0) (proxy #f)
@deffnx {bigloo procedure} webdav-make-directories url #!key (timeout 0) (proxy #f)
Create a directory, respec. a directory hierarchy.
@end deffn

@deffn {bigloo procedure} webdav-rename-file url dst #!key (timeout 0) (proxy #f)
@deffnx {bigloo procedure} webdav-cop-file url dst #!key (timeout 0) (proxy #f)
Rename, respec. copy, a WebDAV file.
@end deffn

@deffn {bigloo procedure} webdav-put-file url obj #!key (timeout 0) (proxy #f)
Create a WebDAV file at @var{url} whose content is @var{obj}.
@end deffn

@node CSS, WebDAV, Web Date, Web
@comment node-name, next, previous, up
@section CSS

CSS files and rules are internally represented as an abstract syntax tree
defined by the @code{css} class hierarchy given belown.

The type of fields whose names end with @code{*} is @code{pair-nil}. The type of
fields whose names end with @code{+} is @code{pair}.

@deffn {class} css-url value::bstring
@deffnx {class} css-ext value::bstring
@deffnx {class} css-stylesheed charset comment* import* rule*-nil
@deffnx {class} css-charset charset::bstring spec::bstring
@deffnx {class} css-comment cdo::bstring cdc::bstring content
@deffnx {class} css-import value medium*
@deffnx {class} css-media medium+ ruleset*
@deffnx {class} css-media-query operator type::bstring expr*
@deffnx {class} css-page ident pseudopage declaration*
@deffnx {class} css-fontface declaration*
@deffnx {class} css-keyframes operator::bstring ident::bstring keyframe*
@deffnx {class} css-pseudopage ident
@deffnx {class} css-ruleset stamp::int specificity selector+ declaration*
@deffnx {class} css-keyframe selector declaration*
@deffnx {class} css-selector element attr*
@deffnx {class} css-selector-class name
@deffnx {class} css-selector-hash name
@deffnx {class} css-selector-name name
@deffnx {class} css-selector-attr ident op arg
@deffnx {class} css-selector-pseudo expr fun
@deffnx {class} css-declaration proprety expr prio
@deffnx {class} css-function fun expr
@deffnx {class} css-hash-color value::bstring
@end deffn

@deffn {bigloo procedure} css-write ast o::output-port
Output a CSS AST into a CSS document.
@end deffn

@deffn {bigloo procedure} css->ast::css-stylesheet i::input-port #!key extension eoff
Parses a CSS document.
@end deffn

@node Web Date, JSON, CSS, Web
@comment node-name, next, previous, up
@section Date

@deffn {bigloo procedure} w3c-datetime-timestamp
Returns the current date as a w3c datetime.
@end deffn

@deffn {bigloo procedure} w3c-datetime->date
@deffnx {bigloo procedure} date->w3c-datetime
Convert from and to Bigloo Dates and W3C dates.
@end deffn

@node JSON, , Web Date, Web
@comment node-name, next, previous, up
@section JSON

@deffn {bigloo procedure} json-parse i::input-port #!key array-alloc array-set array-return object-alloc object-set object-return parse-error (undefined #t) reviver expr constant-alloc string-alloc

Parses a JSON document. The keywored arguments are:

@itemize @bullet
@item @var{array-alloc} a function of 0 argument invoked when parsing an array.
@item @var{array-set} a function of 3 arguments invoked after each array element is parsed. The first argument is the result of the last @code{array-alloc} call. The second argument is the index, and the last, the element value.
@item @var{array-return} a function of two arguments, the allocated array
and the length.
@item @var{object-alloc} a function of 0 argument.
@item @var{object-set} a function of 3 arguments.
@item @var{object-return} a function of 1 argument.
@item @var{parse-error} a function of 3 arguments.
@item @var{undefined} the value used to represent @code{undefined}.
@item @var{constant-alloc} a function of one argument, the parsed contant.
@item @var{string-alloc} a function of one argument, the parsed string.
@item @var{reviver} either @code{#f} or a function of three arguments, invoked
after parsing an object property. 
@item @var{expr} if false, check end-of-file after parsing the last JSON value.
@end itemize

@end deffn
