PiLLoW types

Here are defined the regular types used in the documentation of the predicates of the PiLLoW package.

Usage and interface

Library usage:
:- use_module(library(pillow/pillow_types)).
Exports:
- Regular Types:
  canonic_html_term/1, canonic_xml_term/1, html_term/1, form_dict/1, form_assignment/1, form_value/1, value_dict/1, url_term/1, http_request_param/1, http_response_param/1, http_date/1, weekday/1, month/1, hms_time/1.
Imports:
- Packages:
  prelude, nonpure, condcomp, assertions, isomodes.

Documentation on exports

REGTYPE

A term representing HTML code in canonical, structured way. It is a list of terms defined by the following predicate:

canonic_html_item(comment(S)) :-
        string(S).
canonic_html_item(declare(S)) :-
        string(S).
canonic_html_item(env(Tag,Atts,Terms)) :-
        atm(Tag),
        list(Atts,tag_attrib),
        canonic_html_term(Terms).
canonic_html_item($(Tag,Atts)) :-
        atm(Tag),
        list(Atts,tag_attrib).
canonic_html_item(S) :-
        string(S).

tag_attrib(Att) :-
        atm(Att).
tag_attrib(Att=Val) :-
        atm(Att),
        string(Val).

Each structure represents one HTML construction:

env(tag,attribs,terms): An HTML environment, with name tag, list of attributes attribs and contents terms.
$(tag,attribs): An HTML element of name tag and list of attributes attribs. ($)/2 is defined by the pillow package as an infix, binary operator.
comment(string): An HTML comment (translates to/from ).
declare(string): An HTML declaration, they are used only in the header (translates to/from <!string>).
string: Normal text is represented as a list of character codes.

For example, the term

env(a,[href="www.therainforestsite.com"],
      ["Visit ",img$[src="TRFS.gif"]])

is output to (or parsed from):

<a href="www.therainforestsite.com">Visit <img src="TRFS.gif"></a>

(True) Usage:canonic_html_term(HTMLTerm)

HTMLTerm is a term representing HTML code in canonical form.

REGTYPE

canonic_xml_term/1:

A term representing XML code in canonical, structured way. It is a list of terms defined by the following predicate (see tag_attrib/1 definition in canonic_html_term/1):

canonic_xml_item(Term) :-
        canonic_html_item(Term).
canonic_xml_item(xmldecl(Atts)) :-
        list(Atts,tag_attrib).
canonic_xml_item(env(Tag,Atts,Terms)) :-
        atm(Tag),
        list(Atts,tag_attrib),
        canonic_xml_term(Terms).
canonic_xml_item(elem(Tag,Atts)) :-
        atm(Tag),
        list(Atts,tag_attrib).

In addition to the structures defined by canonic_html_term/1 (the ($)/2 structure appears only in malformed XML code), the following structures can be used:

elem(tag,atts)

Specifies an XML empty element of name tag and list of attributes atts. For example, the term

elem(arc,[weigh="3",begin="n1",end="n2"])

is output to (or parsed from):

<arc weigh="3" begin="n1" end="n2"/>

xmldecl(atts)

Specifies an XML declaration with attributes atts (translates to/from <?xml atts?>)

(True) Usage:canonic_xml_term(XMLTerm)

XMLTerm is a term representing XML code in canonical form.

REGTYPE

html_term/1:

A term which represents HTML or XML code in a structured way. In addition to the structures defined by canonic_html_term/1 or canonic_xml_term/1, the following structures can be used:

begin(tag,atts)

It translates to the start of an HTML environment of name tag and attributes atts. There exists also a begin(tag) structure. Useful, in conjunction with the next structure, when including in a document output generated by an existing piece of code (e.g. tag = pre). Its use is otherwise discouraged.

end(tag)

Translates to the end of an HTML environment of name tag.

start

Used at the beginning of a document (translates to <html>).

end

Used at the end of a document (translates to </html>).

--

Produces a horizontal rule (translates to <hr>).

\

Produces a line break (translates to <br>).

$

Produces a paragraph break (translates to <p>).

image(address)

Used to include an image of address (URL) address (equivalent to img$[src=address]).

image(address,atts)

As above with the list of attributes atts.

ref(address,text)

Produces a hypertext link, address is the URL of the referenced resource, text is the text of the reference (equivalent to a([href=address],text)).

label(name,text)

Labels text as a target destination with label name (equivalent to a([name=name],text)).

heading(n,text)

Produces a heading of level n (between 1 and 6), text is the text to be used as heading. Useful when one wants a heading level relative to another heading (equivalent to hn(text)).

itemize(items)

Produces a list of bulleted items, items is a list of corresponding HTML terms (translates to a <ul> environment).

enumerate(items)

Produces a list of numbered items, items is a list of corresponding HTML terms (translates to a <ol> environment).

description(defs)

Produces a list of defined items, defs is a list whose elements are definitions, each of them being a Prolog sequence (composed by ','/2 operators). The last element of the sequence is the definition, the other (if any) are the defined terms (translates to a <dl> environment).

nice_itemize(img,items)

Produces a list of bulleted items, using the image img as bullet. The predicate icon_address/2 provides a colored bullet.

preformatted(text)

Used to include preformatted text, text is a list of HTML terms, each element of the list being a line of the resulting document (translates to a <pre> environment).

verbatim(text)

Used to include text verbatim, special HTML characters (<,>,&," and space) are translated into its quoted HTML equivalent.

prolog_term(term)

Includes any prolog term term, represented in functional notation. Variables are output as _.

nl

Used to include a newline in the HTML source (just to improve human readability).

entity(name)

Includes the entity of name name (ISO-8859-1 special character).

start_form(addr,atts)

Specifies the beginning of a form. addr is the address (URL) of the program that will handle the form, and atts other attributes of the form, as the method used to invoke it. If atts is not present (there is only one argument) the method defaults to POST.

start_form

Specifies the beginning of a form without assigning address to the handler, so that the form handler will be the cgi-bin executable producing the form.

end_form

Specifies the end of a form.

checkbox(name,state)

Specifies an input of type checkbox with name name, state is on if the checkbox is initially checked.

radio(name,value,selected)

Specifies an input of type radio with name name (several radio buttons which are interlocked must share their name), value is the the value returned by the button, if selected=value the button is initially checked.

input(type,atts)

Specifies an input of type type with a list of attributes atts. Possible values of type are text, hidden, submit, reset, ldots

textinput(name,atts,text)

Specifies an input text area of name name. text provides the default text to be shown in the area, atts a list of attributes.

option(name,val,options)

Specifies a simple option selector of name name, options is the list of available options and val is the initial selected option (if val is not in options the first item is selected by default) (translates to a <select> environment).

menu(name,atts,items)

Specifies a menu of name name, list of attributes atts and list of options items. The elements of the list items are marked with the prefix operator $ to indicate that they are selected (translates to a <select> environment).

form_reply

cgi_reply

This two are equivalent, they do not generate HTML, rather, the CGI protocol requires this content descriptor to be used at the beginning by CGI executables (including form handlers) when replying (translates to Content-type: text/html).

pr

Includes in the page a graphical logo with the message “Developed using the PiLLoW Web programming library”, which points to the manual and library source.

name(text)

A term with functor name/1, different from the special functors defined herein, represents an HTML environment of name name and included text text. For example, the term

   address('clip@clip.dia.fi.upm.es')

is translated into the HTML source

   <address>clip@clip.dia.fi.upm.es</address>

name(atts,text)

A term with functor name/2, different from the special functors defined herein, represents an HTML environment of name name, attributes atts and included text text. For example, the term

   a([href='http://www.clip.dia.fi.upm.es/'],"Clip home")

represents the HTML source

   <a href="http://www.clip.dia.fi.upm.es/">Clip home</a>

(True) Usage:html_term(HTMLTerm)

HTMLTerm is a term representing HTML code.

REGTYPE

form_dict/1:

(True) Usage:form_dict(Dict)

Dict is a dictionary of values of the attributes of a form. It is a list of form_assignment

REGTYPE

form_assignment/1:

(True) Usage:form_assignment(Eq)

Eq is an assignment of value of an attribute of a form. It is defined by:

form_assignment(A=V) :-
        atm(A),
        form_value(V).

form_value(A) :-
        atm(A).
form_value(N) :-
        num(N).
form_value(L) :-
        list(L,string).

REGTYPE

form_value/1:

(True) Usage:form_value(V)

V is a value of an attribute of a form.

REGTYPE

value_dict/1:

(True) Usage:value_dict(Dict)

Dict is a dictionary of values. It is a list of pairs atom=constant.

REGTYPE

url_term/1:

A term specifying an Internet Uniform Resource Locator. Currently only HTTP URLs are supported. Example: http('www.clip.dia.fi.upm.es',80,"/Software/Ciao/"). Defined as

url_term(http(Host,Port,Document)) :-
        atm(Host),
        int(Port),
        string(Document).

(True) Usage:url_term(URL)

URL specifies a URL.

REGTYPE

http_request_param/1:

A parameter of an HTTP request:

head: Specify that the document content is not wanted.
timeout(T): T specifies the time in seconds to wait for the response. Default is 300 seconds.
if_modified_since(Date): Get document only if newer than Date. Date has the format defined by http_date/1.
user_agent(Agent): Provides a user-agent field, Agent is an atom. The string "PiLLoW/1.1" (or whatever version of PiLLoW is used) is appended.
authorization(Scheme,Params): To provide credentials. See RFC 1945 for details.
option(Value): Any unary term, being Value an atom, can be used to provide another valid option (e.g. from('user@machine')).

(True) Usage:http_request_param(Request)

Request is a parameter of an HTTP request.

REGTYPE

http_response_param/1:

A parameter of an HTTP response:

content(String): String is the document content (list of bytes). If the head parameter of the HTTP request is used, an empty list is get here.
status(Type,Code,Reason): Type is an atom denoting the response type, Code is the status code (an integer), and Reason is a string holding the reason phrase.
message_date(Date): Date is the date of the response, with format defined by http_date/1.
location(Loc): This parameter appears when the document has moved, Loc is an atom holding the new location.
http_server(Server): Server is the server responding, as a string.
authenticate(Params): Returned if document is protected, Params is a list of chagenges. See RFC 1945 for details.
allow(Methods): Methods are the methods allowed by the server, as a list of atoms.
content_encoding(Encoding): Encoding is an atom defining the encoding.
content_length(Length): Length is the length of the document (an integer).
content_type(Type,Subtype,Params): Specifies the document content type, Type and Subtype are atoms, Params a list of parameters (e.g. content_type(text,html,[])).
expires(Date): Date is the date after which the entity should be considered stale. Format defined by http_date/1.
last_modified(Date): Date is the date at which the sender believes the resource was last modified. Format defined by http_date/1.
pragma(String): Miscellaneous data.
header(String): Any other functor header/1 is an extension header.

(True) Usage:http_response_param(Response)

Response is a parameter of an HTTP response.

REGTYPE

http_date/1:

http_date(Date)

Date is a term defined as

http_date(date(WeekDay,Day,Month,Year,Time)) :-
        weekday(WeekDay),
        int(Day),
        month(Month),
        int(Year),
        hms_time(Time).

(True) Usage:http_date(Date)

Date is a term denoting a date.

REGTYPE

weekday/1:

(True) Usage:weekday(WeekDay)

WeekDay is a term denoting a weekday.

REGTYPE

month/1:

(True) Usage:month(Month)

Month is a term denoting a month.

REGTYPE

hms_time/1: