◄►The Ciao System » PART VIII - Interfaces to other languages and systems » The PiLLoW Web programming library »

HTML/XML/CGI programming

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

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.

Documentation on exports

PREDICATE
output_html/1:
output_html(HTMLTerm)

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

(True) Usage:

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

PREDICATE
html2terms/2:
html2terms(String,Terms)

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

(True) Usage 1:

Translates an HTML-term into the HTML code it represents.

  • The following properties should hold at call time:
    (term_typing:var/1)String is a free variable.
    (pillow_types:html_term/1)Terms is a term representing HTML code.
  • The following properties hold upon exit:
    (basic_props:string/1)String is a string (a list of character codes).

(True) Usage 2:

Translates HTML code into a structured HTML-term.

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

PREDICATE
xml2terms/2:
xml2terms(String,Terms)

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

(True) Usage 1:

Translates a XML-term into the XML code it represents.

  • The following properties should hold at call time:
    (term_typing:var/1)String is a free variable.
    (pillow_types:html_term/1)Terms is a term representing HTML code.
  • The following properties hold upon exit:
    (basic_props:string/1)String is a string (a list of character codes).

(True) Usage 2:

Translates XML code into a structured XML-term.

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

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

(True) Usage:

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

PREDICATE
html_report_error/1:

(True) Usage:html_report_error(Error)

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. If the flag raw_form_values is off (which is the default state), 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). If the flag on, it gives all values as atoms, without translations.

    (True) Usage:

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

    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).

    (True) Usage:

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

    PREDICATE
    form_empty_value/1:

    (True) Usage:form_empty_value(Term)

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

      PREDICATE
      form_default/3:

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

      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:
        (term_typing:nonvar/1)Val is currently a term which is not a free variable.
        (term_typing:nonvar/1)Default is currently a term which is not a free variable.
        (term_typing:var/1)NewVal is a free variable.

      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.

      (True) Usage:

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

      PREDICATE
      get_cookies/1:
      get_cookies(Cookies)

      Unifies Cookies with a dictionary of attribute=value pairs of the active cookies for this URL. If the flag raw_form_values is on, values are always atoms even if they could be interpreted as numbers.

      (True) Usage:

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

      PREDICATE
      url_query/2:
      url_query(Dict,URLArgs)

      (Deprecated, see url_query_values/2) Translates a dictionary Dict of parameter values into a string URLArgs for appending to a URL pointing to a form handler.

      (True) Usage:

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

      PREDICATE
      url_query_amp/2:
      url_query_amp(Dict,URLArgs)

      Translates a dictionary Dict of parameter values into a string URLArgs for appending to a URL pointing to a form handler to be used in the href of a link (uses &amp; instead of &).

      (True) Usage:

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

      PREDICATE
      url_query_values/2:
      url_query_values(Dict,URLArgs)

      Dict is a dictionary of parameter values and URLArgs is the URL-encoded string of those assignments, which may appear after an URL pointing to a CGI script preceded by a '?'. Dict is computed according to the raw_form_values flag. The use of this predicate is reversible.

      (True) Usage 1:

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

      (True) Usage 2:

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

      PREDICATE
      my_url/1:
      my_url(URL)

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

      (True) Usage:

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

      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.

      (True) Usage 1:

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

      (True) Usage 2:

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

      (True) Usage 3:

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

      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").

      (True) Usage 1:

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

      (True) Usage 2:

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

      PREDICATE
      form_request_method/1:

      (True) Usage:form_request_method(Method)

      Unifies Method with the method of invocation of the form handler (GET or POST).

      • The following properties hold upon exit:
        (basic_props:atm/1)Method is an atom.

      PREDICATE
      icon_address/2:
      icon_address(Img,IAddress)

      The PiLLoW image Img has URL IAddress.

      (True) Usage:

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

      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.

      (True) Usage:

      • The following properties should hold at call time:
        (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
      Meta-predicate with arguments: html_protect(goal).

      PREDICATE
      http_lines/3:

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

      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:
        (basic_props:list/2)Lines is a list of strings.
        (basic_props:string/1)String is a string (a list of character codes).
        (basic_props:string/1)Tail is a string (a list of character codes).

      Documentation on multifiles

      PREDICATE
      define_flag/3:
      Defines a flag as follows: 
      define_flag(raw_form_values,[on,off],off).
      (See Changing system behaviour and various flags).

      If flag is on, values returned by get_form_input/1 are always atoms, unchanged from its original value.

      (Trust) Usage:define_flag(Flag,FlagValues,Default)

      • The following properties hold upon exit:
        (basic_props:atm/1)Flag is an atom.
        (basic_props:flag_values/1)Define the valid flag values
      The predicate is multifile.

      PREDICATE
      html_expansion/2:

      (True) Usage:html_expansion(Term,Expansion)

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

        The predicate is multifile.

        Other information

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

        Module Sections

        Global Links

        Indices

        ◄► 
        Generated with LPdoc using Ciao