:- module(pillow_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
        ],['pillow/ops',assertions,isomodes]).

:- comment(title, "PiLLoW types").

:- comment(author, "Daniel Cabeza").

:- comment(module, "Here are defined the regular types used in the
   documentation of the predicates of the PiLLoW package.").

:- comment(canonic_html_term/1, "A term representing HTML code in
   canonical, structured way.  It is a list of terms defined by the
   following predicate:
   @includedef{canonic_html_item/1} @includedef{tag_attrib/1}
   Each structure represents one HTML construction:
   @begin{description}

   @item{@bf{env(}@em{tag}@bf{,}@em{attribs}@bf{,}@em{terms}@bf{)}} An
   HTML environment, with name @em{tag}, list of attributes @em{attribs}
   and contents @em{terms}.

   @item{@bf{$(}@em{tag}@bf{,}@em{attribs}@bf{)}} An HTML element of
   name @em{tag} and list of attributes @em{attribs}.  @tt{($)/2} is
   defined by the pillow package as an infix, binary operator.

   @item{@bf{comment(}@em{string}@bf{)}} An HTML comment (translates
   to/from @tt{<!--}@em{string}@tt{-->}).

   @item{@bf{declare(}@em{string}@bf{)}} An HTML declaration, they are
   used only in the header (translates to/from
   @tt{<!}@em{string}@tt{>}).

   @item{@em{string}} Normal text is represented as a list of
   character codes.

   @end{description}

   For example, the term
   @begin{verbatim}
env(a,[href=\"www.therainforestsite.com\"],
      [\"Visit \",img$[src=\"TRFS.gif\"]])
   @end{verbatim}
   is output to (or parsed from):
   @begin{verbatim}
<a href=\"www.therainforestsite.com\">Visit <img src=\"TRFS.gif\"></a>
   @end{verbatim}").

:- true prop canonic_html_term(HTMLTerm) + regtype
        # "@var{HTMLTerm} is a term representing HTML code in canonical form.".

canonic_html_term(T) :- list(T,canonic_html_item).

:- true prop canonic_html_item/1 + regtype.

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

:- comment(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 @pred{tag_attrib/1} definition in
   @pred{canonic_html_term/1}): @includedef{canonic_xml_item/1} In
   addition to the structures defined by @pred{canonic_html_term/1}
   (the @tt{($)/2} structure appears only in malformed XML
   code), the following structures can be used: @begin{description}

   @item{@bf{elem(}@em{tag}@bf{,}@em{atts}@bf{)}} Specifies an XML empty
   element of name @em{tag} and list of attributes @em{atts}.
   For example, the term
   @begin{verbatim}
elem(arc,[weigh=""3"",begin=""n1"",end=""n2""])
   @end{verbatim}
   is output to (or parsed from):
   @begin{verbatim}
<arc weigh=""3"" begin=""n1"" end=""n2""/>
   @end{verbatim}

   @item{@bf{xmldecl(}@em{atts}@bf{)}} Specifies an XML declaration with
   attributes @em{atts} (translates to/from @tt{<?xml }@em{atts}@tt{?>})

   @end{description}").

:- true prop canonic_xml_term(XMLTerm) + regtype
        # "@var{XMLTerm} is a term representing XML code in canonical form.".

canonic_xml_term(T) :- list(T,canonic_xml_item).

:- true prop canonic_xml_item/1 + regtype.

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

:- true prop tag_attrib/1 + regtype.

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

:- comment(html_term/1, "A term which represents HTML or XML code in a
   structured way.  In addition to the structures defined by
   @pred{canonic_html_term/1} or @pred{canonic_xml_term/1}, the
   following structures can be used: @begin{description}

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

   @item{@bf{end(}@em{tag}@bf{)}} Translates to the end of an HTML
   environment of name @em{tag}.

   @item{@bf{start}} Used at the beginning of a document (translates to
   @tt{<html>}).

   @item{@bf{end}} Used at the end of a document (translates to
   @tt{</html>}).

   @item{@tt{--}} Produces a horizontal rule (translates to @tt{<hr>}).

   @item{@bf{\\\\}} Produces a line break  (translates to @tt{<br>}).

   @item{@bf{$}}  Produces a paragraph break (translates to  @tt{<p>}).

   @item{@bf{image(}@em{address}@bf{)}} Used to include an image of
   address (URL) @em{address} (equivalent to @tt{img$[src=}@em{address}@tt{]}).

   @item{@bf{image(}@em{address}@bf{,}@em{atts}@bf{)}} As above with
   the list of attributes @em{atts}.

   @item{@bf{ref(}@em{address}@bf{,}@em{text}@bf{)}} Produces a
   hypertext link, @em{address} is the URL of the referenced resource,
   @em{text} is the text of the reference (equivalent to
   @tt{a([href=}@em{address}@tt{],}@em{text}@tt{)}).

   @item{@bf{label(}@em{name}@bf{,}@em{text}@bf{)}} Labels @em{text} as
   a target destination with label @em{name} (equivalent to
   @tt{a([name=}@em{name}@tt{],}@em{text}@tt{)}).

   @item{@bf{heading(}@em{n}@bf{,}@em{text}@bf{)}} Produces a heading of
   level @em{n} (between 1 and 6), @em{text} is the text to be used as
   heading.  Useful when one wants a heading level relative to another
   heading (equivalent to @tt{h}@em{n}@tt{(}@em{text}@tt{)}).

   @item{@bf{itemize(}@em{items}@bf{)}} Produces a list of bulleted
   items, @em{items} is a list of corresponding HTML terms (translates
   to a @tt{<ul>} environment).

   @item{@bf{enumerate(}@em{items}@bf{)}} Produces a list of numbered
    items, @em{items} is a list of corresponding HTML terms (translates
    to a @tt{<ol>} environment).

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

   @item{@bf{nice_itemize(}@em{img}@bf{,}@em{items}@bf{)}} Produces a
   list of bulleted items, using the image @em{img} as bullet. The
   predicate @pred{icon_address/2} provides a colored bullet.

   @item{@bf{preformatted(}@em{text}@bf{)}} Used to include preformatted
   text, @em{text} is a list of HTML terms, each element of the list
   being a line of the resulting document (translates to a @tt{<pre>}
   environment).

   @item{@bf{verbatim(}@em{text}@bf{)}} Used to include text verbatim,
   special HTML characters (@tt{<,>,&,""} and space) are translated into its
   quoted HTML equivalent.

   @item{@bf{prolog_term(}@em{term}@bf{)}} Includes any prolog term
   @em{term}, represented in functional notation.  Variables are output
   as @tt{_}.

   @item{@bf{nl}} Used to include a newline in the HTML source (just to
   improve human readability).

   @item{@bf{entity(}@em{name}@bf{)}} Includes the entity of name
   @em{name} (ISO-8859-1 special character).

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

   @item{@bf{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.

   @item{@bf{end_form}} Specifies the end of a form.

   @item{@bf{checkbox(}@em{name}@bf{,}@em{state}@bf{)}} Specifies an
   input of type @tt{checkbox} with name @em{name}, @em{state} is
   @tt{on} if the checkbox is initially checked.

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

   @item{@bf{input(}@em{type}@bf{,}@em{atts}@bf{)}} Specifies an input
   of type @em{type} with a list of attributes @em{atts}.  Possible
   values of @em{type} are @tt{text}, @tt{hidden}, @tt{submit},
   @tt{reset}, \ldots

   @item{@bf{textinput(}@em{name}@bf{,}@em{atts}@bf{,}@em{text}@bf{)}}
   Specifies an input text area of name @em{name}. @em{text} provides
   the default text to be shown in the area, @em{atts} a list of
   attributes.

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

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

   @item{@bf{form_reply}} @item{@bf{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
   @tt{Content-type: text/html}).

   @item{@bf{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.

   @item{@em{name}@bf{(}@em{text}@bf{)}} A term with functor
   @em{name}/1, different from the special functors defined herein,
   represents an HTML environment of name @em{name} and included text
   @em{text}. For example, the term @begin{verbatim}
   address('clip@@clip.dia.fi.upm.es')
   @end{verbatim} is translated into
   the HTML source @begin{verbatim}
   <address>clip@@clip.dia.fi.upm.es</address>
   @end{verbatim}

   @item{@em{name}@bf{(}@em{atts}@bf{,}@em{text}@bf{)}} A term with
   functor @em{name}/2, different from the special functors defined
   herein, represents an HTML environment of name @em{name}, attributes
   @em{atts} and included text @em{text}. For example, the term
   @begin{verbatim}

   a([href='http://www.clip.dia.fi.upm.es/'],\"Clip home\")
   @end{verbatim} represents the HTML source @begin{verbatim}
   <a href=\"http://www.clip.dia.fi.upm.es/\">Clip home</a>
   @end{verbatim}

   @end{description}
  ").


:- true prop html_term(HTMLTerm) + regtype
        # "@var{HTMLTerm} is a term representing HTML code.".

html_term(_).

:- comment(url_term/1, "A term specifying an Internet Uniform Resource
   Locator. Currently only HTTP URLs are supported.  Example:
   @tt{http('www.clip.dia.fi.upm.es',80,\"/Software/Ciao/\")}.  Defined as
   @includedef{url_term/1}").
:- true prop url_term(URL) + regtype # "@var{URL} specifies a URL.".

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

:- comment(http_request_param/1, "A parameter of an HTTP request:
   @begin{itemize}
   @item @bf{head:} Specify that the document content is not wanted.

   @item @bf{timeout(}@em{T}@bf{):} @em{T} specifies the time in seconds
   to wait for the response.  Default is 300 seconds.

   @item @bf{if_modified_since(}@em{Date}@bf{):} Get document only if
   newer than @em{Date}.  @em{Date} has the format defined by
   @pred{http_date/1}.

   @item @bf{user_agent(}@em{Agent}@bf{):} Provides a user-agent field,
   @em{Agent} is an atom.  The string @tt{\"PiLLoW/1.1\"} (or whatever
   version of PiLLoW is used) is appended.

   @item @bf{authorization(}@em{Scheme},@em{Params}@bf{):} To provide
   credentials.  See RFC 1945 for details.

   @item @bf{@em{option}(}@em{Value}@bf{):} Any unary term, being
   @em{Value} an atom, can be used to provide another valid option (e.g.
   @tt{from('user@@machine')}). @comment{}
   @end{itemize}
").

:- true prop form_dict(Dict) + regtype
        # "@var{Dict} is a dictionary of values of the attributes of a
          form.  It is a list of @tt{form_assignment}".

form_dict(Dict) :- list(Dict,form_assignment).

:- true prop form_assignment(Eq) + regtype
        # "@var{Eq} is an assignment of value of an attribute of a form.
          It is defined by:
          @includedef{form_assignment/1} @includedef{form_value/1}".

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

:- true prop form_value(V) + regtype
        # "@var{V} is a value of an attribute of a form.".

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

:- true prop value_dict(Dict) + regtype
        # "@var{Dict} is a dictionary of values. It is a list of
           pairs @em{atom}=@em{constant}.".

value_dict(Dict) :- list(Dict,value_assignment).

value_assignment(A=V) :-
        atm(A),
        constant(V).

:- true prop http_request_param(Request) + regtype # "@var{Request} is a
   parameter of an HTTP request.".

http_request_param(_).

:- comment(http_response_param/1, "A parameter of an HTTP response:
   @begin{itemize}

   @item @bf{content(}@em{String}@bf{):} @em{String} is the document
   content (list of bytes).  If the @tt{head} parameter of the HTTP
   request is used, an empty list is get here.

   @item @bf{status(}@em{Type,Code,Reason}@bf{):} @em{Type} is an atom
   denoting the response type, @em{Code} is the status code (an integer),
   and @em{Reason} is a string holding the reason phrase.

   @item @bf{message_date(}@em{Date}@bf{):} @em{Date} is the date of the
   response, with format defined by @pred{http_date/1}.

   @item @bf{location(}@em{Loc}@bf{):} This parameter appears when the
   document has moved, @em{Loc} is an atom holding the new location.

   @item @bf{http_server(}@em{Server}@bf{):} @em{Server} is the server
   responding, as a string.

   @item @bf{authenticate(}@em{Params}@bf{):} Returned if document is
   protected, @em{Params} is a list of chagenges.  See RFC 1945 for details.

   @item @bf{allow(}@em{Methods}@bf{):} @em{Methods} are the methods
   allowed by the server, as a list of atoms.

   @item @bf{content_encoding(}@em{Encoding}@bf{):} @em{Encoding} is an
   atom defining the encoding.

   @item @bf{content_length(}@em{Length}@bf{):} @em{Length} is the
   length of the document (an integer). @comment{}

   @item @bf{content_type(}@em{Type,Subtype,Params}@bf{):} Specifies the
   document content type, @em{Type} and @em{Subtype} are atoms, @em{Params}
   a list of parameters (e.g.  @tt{content_type(text,html,[])}). @comment{}

   @item @bf{expires(}@em{Date}@bf{):} @em{Date} is the date after which
   the entity should be considered stale.  Format defined by
   @pred{http_date/1}.

   @item @bf{last_modified(}@em{Date}@bf{):} @em{Date} is the date at
   which the sender believes the resource was last modified.  Format
   defined by @pred{http_date/1}.

   @item @bf{pragma(}@em{String}@bf{):} Miscellaneous data.

   @item @bf{@em{header}(}@em{String}@bf{):} Any other functor
   @em{header}/1 is an extension header.
   @end{itemize}
").

:- true prop http_response_param(Response) + regtype # "@var{Response}
   is a parameter of an HTTP response.".

http_response_param(_).

:- comment(http_date(Date), "@var{Date} is a term defined as
   @includedef{http_date/1}.").
:- true prop http_date(Date) + regtype # "@var{Date} is a term denoting
   a date.".

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

:- true prop weekday(WeekDay) + regtype # "@var{WeekDay} is a term
   denoting a weekday.".

weekday('Monday').
weekday('Tuesday').
weekday('Wednesday').
weekday('Thursday').
weekday('Friday').
weekday('Saturday').
weekday('Sunday').

:- true prop month(Month) + regtype # "@var{Month} is a term denoting
   a month.".

month('January').
month('February').
month('March').
month('April').
month('May').
month('June').
month('July').
month('August').
month('September').
month('October').
month('November').
month('December').

:- true prop hms_time(Time) + regtype # "@var{Time} is an atom of the form
   @tt{hh:mm:ss}".

hms_time(T) :- atm(T).


:- comment(version_maintenance,dir('../../version')).

:- comment(version(1*9+253,2003/12/30,22:44*55+'CET'), "Added comment
   for weekday/1 and month/1.  (Edison Mera)").

