The PiLLoW Web Programming Library - HTML/XML/CGI programming

Go to the first, previous, next, last section, table of contents.

# HTML/XML/CGI programming

Author(s): Daniel Cabeza, Manuel Hermenegildo, Sacha Varma.

Version: 1.7 (2000/7/12, 19:1:20 CEST)

Version of last change: 1.5#114 (2000/4/11, 20:23:43 CEST)

This module implements the predicates of the PiLLoW package related to HTML/ XML generation and parsing, CGI and form handlers programming, and in general all the predicates which do not imply the use of the HTTP protocol.

- Usage and interface (html)
- Documentation on exports (html)
- Documentation on multifiles (html)
- Other information (html)

## Usage and interface (`html`)

- Library usage: `:- use_module(library(html)).`
- Exports:
  - Predicates: `output_html/1`, `html2terms/2`, `xml2terms/2`, `html_template/3`, `html_report_error/1`, `get_form_input/1`, `get_form_value/3`, `form_empty_value/1`, `form_default/3`, `set_cookie/2`, `get_cookies/1`, `url_query/2`, `my_url/1`, `url_info/2`, `url_info_relative/3`, `form_request_method/1`, `icon_address/2`, `html_protect/1`, `http_lines/3`.
  - Multifiles: `html_expansion/2`.

## Documentation on exports (`html`)

PREDICATE: output_html/1:

  `output_html(HTMLTerm)`

  Outputs `HTMLTerm`, interpreted as an `html_term/1`, to current output stream.

  Usage:

  - The following properties should hold at call time: `HTMLTerm` is a term representing HTML code. (`html_term/1`)

PREDICATE: html2terms/2:

  `html2terms(String,Terms)`

  `String` is a character list containing HTML code and `Terms` is its prolog structured representation.

  Usage 1:

  - Description: Translates an HTML-term into the HTML code it represents.
  - The following properties should hold at call time: `String` is a free variable. (`var/1`) `Terms` is a term representing HTML code. (`html_term/1`)
  - The following properties hold upon exit: `String` is a string (a list of character codes). (`string/1`)

  Usage 2:

  - Description: Translates HTML code into a structured HTML-term.
  - Calls should, and exit will be compatible with: `Terms` is a term representing HTML code in canonical form. (`canonic_html_term/1`)
  - The following properties should hold at call time: `String` is a string (a list of character codes). (`string/1`)
  - The following properties hold upon exit: `Terms` is a term representing HTML code in canonical form. (`canonic_html_term/1`)

PREDICATE: xml2terms/2:

  `xml2terms(String,Terms)`

  `String` is a character list containing XML code and `Terms` is its prolog structured representation.

  Usage 1:

  - Description: Translates a XML-term into the XML code it represents.
  - The following properties should hold at call time: `String` is a free variable. (`var/1`) `Terms` is a term representing HTML code. (`html_term/1`)
  - The following properties hold upon exit: `String` is a string (a list of character codes). (`string/1`)

  Usage 2:

  - Description: Translates XML code into a structured XML-term.
  - Calls should, and exit will be compatible with: `Terms` is a term representing XML code in canonical form. (`canonic_xml_term/1`)
  - The following properties should hold at call time: `String` is a string (a list of character codes). (`string/1`)
  - The following properties hold upon exit: `Terms` is a term representing XML code in canonical form. (`canonic_xml_term/1`)

PREDICATE: html_template/3:

  `html_template(Chars,Terms,Dict)`

  Interprets `Chars` as an HTML template returning in `Terms` the corresponding structured HTML-term, which includes variables, and unifying `Dict` with a dictionary of those variables (an incomplete list of name`=`Var pairs). An HTML template is standard HTML code, but in which "slots" can be defined and given an identifier. These slots represent parts of the HTML code in which other HTML code can be inserted, and are represented in the HTML-term as free variables. There are two kinds of variables in templates:

  - Variables representing page contents. A variable with name name is defined with the special tag `<V>`name`</V>`.
  - Variables representing tag attributes. They occur as an attribute or an attribute value starting with `_`, followed by its name, which must be formed by alphabetic characters.

  As an example, suposse the following HTML template:

      <html>
      <body bgcolor=_bgcolor>
      <v>content</v>
      </body>
      </html>

  The following query in the Ciao toplevel shows how the template is parsed, and the dictionary returned:

      ?- file_to_string('template.html',_S), html_template(_S,Terms,Dict).

      Dict = [bgcolor=_A,content=_B|_],
      Terms = [env(html,[],["
      ",env(body,[bgcolor=_A],["
      ",_B,"
      "]),"
      "]),"
      "] ?

      yes

  If a dictionary with values is supplied at call time, then variables are unified accordingly inside the template:

      ?- file_to_string('template.html',_S),
         html_template(_S,Terms,[content=b("hello world!"),bgcolor="white"]).

      Terms = [env(html,[],["
      ",env(body,[bgcolor="white"],["
      ",b("hello world!"),"
      "]),"
      "]),"
      "] ?

      yes

  Usage:

  - Calls should, and exit will be compatible with: `Terms` is a term representing HTML code in canonical form. (`canonic_html_term/1`) `Dict` is a list. (`list/1`)
  - The following properties should hold at call time: `Chars` is a string (a list of character codes). (`string/1`)
  - The following properties hold upon exit: `Terms` is a term representing HTML code in canonical form. (`canonic_html_term/1`) `Dict` is a list. (`list/1`)

PREDICATE: html_report_error/1:

  Usage: `html_report_error(Error)`

  - Description: Outputs error `Error` as a standard HTML page.

PREDICATE: get_form_input/1:

  `get_form_input(Dict)`

  Translates input from the form (with either the POST or GET methods, and even with CONTENT_TYPE multipart/form-data) to a dictionary `Dict` of attribute=value pairs. It translates empty values (which indicate only the presence of an attribute) to the atom `'$empty'`, values with more than one line (from text areas or files) to a list of lines as strings, the rest to atoms or numbers (using `name/2`).

  Usage:

  - The following properties should hold at call time: `Dict` is a free variable. (`var/1`)
  - The following properties hold upon exit: `Dict` is a dictionary of values of the attributes of a form. It is a list of `form_assignment` (`form_dict/1`)

PREDICATE: get_form_value/3:

  `get_form_value(Dict,Var,Val)`

  Unifies `Val` with the value for attribute `Var` in dictionary `Dict`. Does not fail: value is `"` if not found (this simplifies the programming of form handlers when they can be accessed directly).

  Usage:

  - Calls should, and exit will be compatible with: `Val` is a value of an attribute of a form. (`form_value/1`)
  - The following properties should hold at call time: `Dict` is a dictionary of values of the attributes of a form. It is a list of `form_assignment` (`form_dict/1`) `Var` is an atom. (`atm/1`)
  - The following properties hold upon exit: `Val` is a value of an attribute of a form. (`form_value/1`)

PREDICATE: form_empty_value/1:

  Usage: `form_empty_value(Term)`

  - Description: Checks that `Term`, a value comming from a text area is empty (can have spaces, newlines and linefeeds).

PREDICATE: form_default/3:

  Usage: `form_default(Val,Default,NewVal)`

  - Description: Useful when a form is only partially filled, or when the executable can be invoked either by a link or by a form, to set form defaults. If the value of `Val` is empty then `NewVal`=`Default`, else `NewVal`=`Val`.
  - The following properties should hold at call time: `Val` is currently a term which is not a free variable. (`nonvar/1`) `Default` is currently a term which is not a free variable. (`nonvar/1`) `NewVal` is a free variable. (`var/1`)

PREDICATE: set_cookie/2:

  `set_cookie(Name,Value)`

  Sets a cookie of name `Name` and value `Value`. Must be invoked before outputting any data, including the `cgi_reply` html-term.

  Usage:

  - The following properties should hold at call time: `Name` is an atom. (`atm/1`) `Value` is an atomic term (an atom or a number). (`constant/1`)

PREDICATE: get_cookies/1:

  `get_cookies(Cookies)`

  Unifies `Cookies` with a dictionary of attribute=value pairs of the active cookies for this URL.

  Usage:

  - The following properties should hold at call time: `Cookies` is a free variable. (`var/1`)
  - The following properties hold upon exit: `Cookies` is a dictionary of values. It is a list of pairs atom=constant. (`value_dict/1`)

PREDICATE: url_query/2:

  `url_query(Dict,URLArgs)`

  Translates a dictionary `Dict` of parameter values into a string `URLArgs` for appending to a URL pointing to a form handler.

  Usage:

  - The following properties should hold at call time: `Dict` is a dictionary of values. It is a list of pairs atom=constant. (`value_dict/1`) `URLArgs` is a free variable. (`var/1`)
  - The following properties hold upon exit: `URLArgs` is a string (a list of character codes). (`string/1`)

PREDICATE: my_url/1:

  `my_url(URL)`

  Unifies `URL` with the Uniform Resource Locator (WWW address) of this cgi executable.

  Usage:

  - Calls should, and exit will be compatible with: `URL` is a string (a list of character codes). (`string/1`)
  - The following properties hold upon exit: `URL` is a string (a list of character codes). (`string/1`)

PREDICATE: url_info/2:

  `url_info(URL,URLTerm)`

  Translates a URL `URL` to a Prolog structure `URLTerm` which details its various components, and vice-versa. For now non-HTTP URLs make the predicate fail.

  Usage 1:

  - Calls should, and exit will be compatible with: `URLTerm` specifies a URL. (`url_term/1`)
  - The following properties should hold at call time: `URL` is an atom. (`atm/1`)
  - The following properties hold upon exit: `URLTerm` specifies a URL. (`url_term/1`)

  Usage 2:

  - Calls should, and exit will be compatible with: `URLTerm` specifies a URL. (`url_term/1`)
  - The following properties should hold at call time: `URL` is a string (a list of character codes). (`string/1`)
  - The following properties hold upon exit: `URLTerm` specifies a URL. (`url_term/1`)

  Usage 3:

  - The following properties should hold at call time: `URL` is a free variable. (`var/1`) `URLTerm` specifies a URL. (`url_term/1`)
  - The following properties hold upon exit: `URL` is a string (a list of character codes). (`string/1`)

PREDICATE: url_info_relative/3:

  `url_info_relative(URL,BaseURLTerm,URLTerm)`

  Translates a relative URL `URL` which appears in the HTML page refered to by `BaseURLTerm` into `URLTerm`, a Prolog structure containing its absolute parameters. Absolute URLs are translated as with `url_info/2`. E.g.

      url_info_relative("dadu.html",
                        http('www.foo.com',80,"/bar/scoob.html"), Info)

  gives `Info = http('www.foo.com',80,"/bar/dadu.html")`.

  Usage 1:

  - Calls should, and exit will be compatible with: `URLTerm` specifies a URL. (`url_term/1`)
  - The following properties should hold at call time: `URL` is an atom. (`atm/1`) `BaseURLTerm` specifies a URL. (`url_term/1`)
  - The following properties hold upon exit: `URLTerm` specifies a URL. (`url_term/1`)

  Usage 2:

  - Calls should, and exit will be compatible with: `URLTerm` specifies a URL. (`url_term/1`)
  - The following properties should hold at call time: `URL` is a string (a list of character codes). (`string/1`) `BaseURLTerm` specifies a URL. (`url_term/1`)
  - The following properties hold upon exit: `URLTerm` specifies a URL. (`url_term/1`)

PREDICATE: form_request_method/1:

  Usage: `form_request_method(Method)`

  - Description: Unifies `Method` with the method of invocation of the form handler (`GET` or `POST`).
  - The following properties hold upon exit: `Method` is an atom. (`atm/1`)

PREDICATE: icon_address/2:

  `icon_address(Img,IAddress)`

  The PiLLoW image `Img` has URL `IAddress`.

  Usage:

  - Calls should, and exit will be compatible with: `Img` is an atom. (`atm/1`) `IAddress` is an atom. (`atm/1`)
  - The following properties hold upon exit: `Img` is an atom. (`atm/1`) `IAddress` is an atom. (`atm/1`)

PREDICATE: html_protect/1:

  `html_protect(Goal)`

  Calls `Goal`. If an error occurs during its execution, or it fails, an HTML page is output informing about the incident. Normaly the whole execution of a CGI is protected thus.

  Meta-predicate with arguments: `html_protect(goal)`.

  Usage:

  - Calls should, and exit will be compatible with: `Goal` is a term which represents a goal, i.e., an atom or a structure. (`callable/1`)

PREDICATE: http_lines/3:

  Usage: `http_lines(Lines,String,Tail)`

  - Description: `Lines` is a list of the lines with occur in `String` until `Tail`. The lines may end UNIX-style or DOS-style in `String`, in `Lines` they have not end of line characters. Suitable to be used in DCGs.
  - Calls should, and exit will be compatible with: `Lines` is a list of `string`s. (`list/2`) `String` is a string (a list of character codes). (`string/1`) `Tail` is a string (a list of character codes). (`string/1`)

## Documentation on multifiles (`html`)

PREDICATE: html_expansion/2:

  The predicate is multifile.

  Usage: `html_expansion(Term,Expansion)`

  - Description: Hook predicate to define macros. Expand occurrences of `Term` into `Expansion`, in `output_html/1`. Take care to not transform something into itself!

## Other information (`html`)

The code uses input from from L. Naish's forms and F. Bueno's previous Chat interface. Other people who have contributed is (please inform us if we leave out anybody): Markus Fromherz, Samir Genaim.

Go to the first, previous, next, last section, table of contents.