1:- module(pwp, 2 [ pwp_files/2, % +FileIn, +FileOut 3 pwp_stream/3, % +StreamIn, +StreamOut, +Context 4 pwp_xml/3 % +DomIn, -DOMOut, +Context 5 ]). 6:- autoload(library(lists),[append/3]). 7:- autoload(library(readutil),[read_file_to_codes/3]). 8:- autoload(library(sgml),[load_xml_file/2]). 9:- autoload(library(sgml_write),[xml_write/3]).

Prolog Well-formed Pages

PWP is an approach to server-side scripting using Prolog which is based on a simple key principle:

The source form of a PWP should be WELL-FORMED XML

Especially when generating XML rather than HTML, this is such an obvious thing to do. We have many kinds of XML checking tools.

We can tell whether an XML document is WELL FORMED (all the punctuation is right, all tags balance) using practically any decent parser, including SWI Prolog's 'sgml'.
If we can write a Document Type Description then we can check that a document is VALID using tools like Open SP (formerly James Clark's SP) or SWI Prolog's 'sgml'. This does not guarantee that the output will be valid, but it does catch a lot of errors very early.
If we can write an XML Schema then we can check that a document is schema-valid. (SWI Prolog's 'sgml' does not yet come with a schema validator, but who knows what the future holds?).
Since an XML document is just a data structure, we can use any checking tool that we can write in Prolog, IF the input is well-formed so that we can load a template as a Prolog data structure.

Having decided that the input should be well formed, that means NO NEW SYNTAX

None of the weird and horrible <% ... %> or whatever not-quite-XML stuff you see in other template systems, making checking so very hard (and therefore, making errors so distressingly common).

That in turns means that PWP "markup" must be based on special elements or special attributes. The fact that an XML parser must allow undeclared attributes on any element even when validating, but must not allow undeclared elements, suggests doing this through attributes. In particular, one should be able to take an existing DTD, such as an XHTML DTD, and just use that without modification. So the design reduces to

Allow dynamic data selection, insertion, and transformation just using a small number of extra attributes.

This description uses the following name space:

xmlns:pwp='http://www.cs.otago.ac.nz/staffpriv/ok/pwp.pl'

The attributes are

pwp:ask = Query
pwp:use = Term
pwp:how = text | xml
pwp:tag = QName or '-'
pwp:att = '' | 'one non-alphanumeric character'

Here's what they mean. Each element is expanded in the context of a set of variable bindings. After expansion, if the tag is not mapped to '-', all attributes in the pwp: namespace are removed and the children elements are recursively expanded.

pwp:ask = Query
- Query is a Prolog goal. For each solution of Query, the element is further processed with the new variables of Query added to the context.
- If Query is not a well formed Prolog goal, or if execution of Query throws an exception, page transformation comes to a complete halt and no page is generated.
pwp:use = Term
pwp:how = text | xml | text-file | xml-file | pwp-file
```
Term is a Prolog term; variables in Term are bound by the context.
An empty Term is regarded as a missing value for this attribute.
The Prolog variable CONTEXT refers to the entire context, a list
of Name = Value, where Name is a Prolog atom holding the name of        the context variable and Value is an arbitrary Prolog term.
```
- If pwp:how is text, The value of Term is used to define a sequence of characters.
  - A number produces the same characters that write/1 would.
  - An atom produces the same characters that write/1 would.
  - A string produces the same characters that write/1 would.
  - A list of character codes produces those characters.
  - The following terms produce the same sequence of characters that the corresponding goal would have sent to the current output stream:
    - write(Datum)
    - writeq(Datum)
    - write_canonical(Datum)
    - print(Datum)
    - print(Datum)
    - format(Format)
    - format(Format, Arguments)
  - A singleton list [X] defines the characters that X defines.
  - Any other term F(T1,...,Tn) defines the characters that T1 defines, followed by the characters that T2 defines, ..., followed by the characters that Tn defines.
- If pwp:how is xml, The value of Term must be an XML term as defined in the SGML2PL documentation or a list of such terms. A single term is taken as if it had been [Term]. The resulting list of terms replaces the children of the current element and will not be further processed.
- If pwp:how is text-file, The value of Term is used to define a sequence of characters. That sequence of characters is used as a file name. The file is read as a sequence of characters, and that sequence used as character data.
- If pwp:how is xml-file, The value of Term is used to define a sequence of characters. That sequence of characters is used as a file name. The file is loaded as XML, and the sequence of XML items thus obtained used. This means that PWP provides XML inclusion without depending on the parser to support XInclude.
- If pwp:how is pwp-file, Like xml-file, but PWP attributes are evaluated and processed. The current context variables are passed to the PWP processor.
  The default value for pwp:how is text.

pwp:tag = QName or '-'

If pwp:tag is missing or the value is empty, the current element
appears in the output (after further processing) with its present
tag.  If pwp:tag is a QName, the current element appears (...)
with that as its tag.  That option is most useful in DTDs, where
an "authoring" DTD may use one tag and have it automatically mapped
to another tag in the output, e.g., <item> -> <li>.  Finally, if
pwp:tag is '-', the children of the current element (either the
result of pwp:use or the transformed original children, whichever
applies) appear in the output but there is no element around them.

A missing or empty pwp:ask is just like pwp:ask = 'true'.

pwp:att = '' | 'one non-alphanumeric character'.

Attributes in the pwp namespace are not affected by this attribute.
Such attributes are always stripped out and never substituted into.

If pwp:att is missing or empty, attributes of the current
element are copied over to the output unchanged.

If pwp:att = 'c' for some non-alphanumeric character c,
each attribute is examined for occurrences of c(...)c and c[...]c
which are as short as possible.
There is no one character which could be used every time, so you
have to explicitly choose a substitution marker which is safe
for the data you do not want to be altered.  None of the pwp
attributes are inherited, least of all this one.

Text outside c(...)c groups is copied unchanged; text inside
a c(...)c group is parsed as a Prolog term and treated as if by
pwp:how = text. Text inside a c[...]c group is evaluated (in the
current context), and if it fails, the entire attribute will be
removed from the element.

Examples:

A "Hello World" like example
```
<html
 xmlns:pwp="http://www.cs.otago.ac.nz/staffpriv/ok/pwp.pl"
 pwp:ask = "ensure_loaded(msg), once(msg(Greeting))">
 <head>
 <title pwp:use="Greeting"/>
 </head>
 <body>
 
 </body>
</html>
```
where msg.pl contains
```
msg('Hello, World!').
```
This example illustrates an important point. Prolog Well-Formed Pages provide NO way to physically incorporate Prolog clauses into a page template. Prolog clauses must be put in separate files which can be checked by a Prolog syntax checker, compiler, cross-referencer, &c WITHOUT the Prolog tool in question needing to know anything whatsoever about PWP. You load the files using pwp:ask on the root element.

Binding some variables and using them

<html
  xmlns:pwp="http://www.cs.otago.ac.nz/staffpriv/ok/pwp.pl">
  <head><title>Example 2</title></head>
  <body pwp:ask="Hello = 'Hello world', A = 20, B = 22">
    <h1 pwp:use="Hello"/>
    <p>The answer is <span pwp:use="C" pwp:ask="C is A+B"/>.</p>
  </body>
</html>

Making a table We are given a Prolog database staff.pl defining staff(NickName, FullName, Office, Phone, E_Mail_Address). status(NickName, full_time | part_time). We want to make a phone list of full time staff.

<html
  xmlns:pwp="http://www.cs.otago.ac.nz/staffpriv/ok/pwp.pl"
  pwp:ask='ensure_loaded(staff)'>
  <head>
    <title>Phone list for Full-Time staff.</title>
  </head>
  <body>
    <h1>Phone list for Full-Time staff.</h1>
    <table
      pwp:ask = "setof(FullName-Phone,
                       N^O^E^(
                         status(N, full_time),
                         staff(N, FullName, O, Phone, E)
                       ),
                       Staff_List)">
      <tr><th>Name</th><th>Phone</th></tr>
      <tr pwp:ask="member(FullName-Phone, Staff_List)">
        <td pwp:use="FullName"/>
        <td pwp:use="Phone"/>
      </tr>
    </table>
  </body>
</html>

Substituting into an attribute Same data base as before, but now we want to make a mailing list page.

<html
  xmlns:pwp="http://www.cs.otago.ac.nz/staffpriv/ok/pwp.pl"
  pwp:ask='ensure_loaded(staff)'>
  <head>
    <title>Phone list for Full-Time staff.</title>
  </head>
  <body>
    <h1>Phone list for Full-Time staff.</h1>
    <table
      pwp:ask = "setof(FullName-E_Mail,
                       N^O^P^staff(N, FullName, O, P, E_Mail),
                       Staff_List)">
      <tr><th>Name</th><th>Address</th></tr>
      <tr pwp:ask="member(FullName-E_Mail, Staff_List)">
        <td pwp:use="FullName"/>
        <td><a pwp:use="E_Mail"
               pwp:att='$' href="mailto:$(E_Mail)$"/></td>
      </tr>
    </table>
  </body>
</html>

If-then-else effect A page that displays the value of the 'SHELL' environment variable if it has one, otherwise displays 'There is no default shell.'
```
<html
 xmlns:pwp="http://www.cs.otago.ac.nz/staffpriv/ok/pwp.pl">
 <head><title>$SHELL</title></head>
 <body>
 The default shell is .
 There is no default shell.
 </body>
</html>
```
There is one other criterion for a good server-side template language:

It should be possible to compile templates so as to eliminate most if not all interpretation overhead.

This particular notation satisfies that criterion with the limitation that the conversion of a term to character data requires run-time traversal of terms (because the terms are not known until run time).

author: - Richard O'Keefe
To be done: - Support compilation of PWP input files */

332pwp_files(M:In, Out) :- 333 load_xml_file(In, Contents), 334 pwp_xml(M:Contents, Transformed, []), 335 !, 336 setup_call_cleanup(open(Out, write, Output), 337 xml_write(Output, Transformed, []), 338 close(Output)).

349pwp_stream(M:Input, Output, Context) :- 350 load_xml_file(stream(Input), Contents), 351 pwp_xml(M:Contents, Transformed, Context), 352 !, 353 xml_write(Output, Transformed, []). 354 355 356/* Recall that an XML term is one of 357 358 <atom> Character Data 359 sdata(...) SDATA (SGML only) 360 ndata(...) NDATA 361 pi(...) Processing instruction 362 363 element(Name, [Att...], [Child...]) 364 365 where Att is Attribute=Value and Child is an XML term. 366 367 We are only concerned with elements; all other XML terms are 368 left alone. I have given some thought to recognising 369 370 <?pwp ...Command...?> 371 372 processing instructions, executing the Command, and removing 373 the processing instructions, as a debugging tool. But this 374 is a proof-of-concept implementation; debugging features can 375 wait for The Real Thing. 376*/

386pwp_xml(M:In, Out, Context) :- 387 pwp_list(In, Out, M, Context). 388 389pwp_list([], [], _, _). 390pwp_list([element(Tag0,Atts0,Kids0)|Xs], Ys0, M, Context) :- 391 !, 392 pwp_attributes(Atts0, Ask, Use, How, Att, Tag1, Atts1), 393 ( nonvar(Tag1), Tag1 \== '' -> Tag2 = Tag1 394 ; Tag2 = Tag0 395 ), 396 ( nonvar(Ask), Ask \== '', Ask \== 'true' 397 -> atom_to_term(Ask, Query, Bindings), 398 pwp_unite(Bindings, Context, Context1), 399 findall(Xml, 400 ( M:Query, 401 pwp_element(Tag2, Atts1, Kids0, Use, How, Att, 402 M, Context1, Xml)), 403 NewContent) 404 ; /* Ask is missing, empty, or true */ 405 pwp_element(Tag2, Atts1, Kids0, Use, How, Att, 406 M, Context, NewContent) 407 ), 408 pwp_attach(NewContent, Ys0, Ys1), 409 pwp_list(Xs, Ys1, M, Context). 410pwp_list([X|Xs], [X|Ys], M, Context) :- 411 pwp_list(Xs, Ys, M, Context).

426pwp_attributes([], _, _, _, _, _, []). 427pwp_attributes([AV|AVs], Ask, Use, How, Att, Tag, New_Atts1) :- 428 AV = (Name=Value), 429 ( pwp_attr(Name, PWPName) 430 -> ( pwp_attr(PWPName, Value, Ask, Use, How, Att, Tag) 431 -> New_Atts1 = New_Atts2 432 ; New_Atts1 = New_Atts2 433 ) 434 ; New_Atts1 = [AV|New_Atts2] 435 ), 436 pwp_attributes(AVs, Ask, Use, How, Att, Tag, New_Atts2). 437 438 439pwp_attr(ask, Value, Value, _Use, _How, _Att, _Tag). 440pwp_attr(use, Value, _Ask, Value, _How, _Att, _Tag). 441pwp_attr(how, Value, _Ask, _Use, Value, _Att, _Tag). 442pwp_attr(att, Value, _Ask, _Use, _How, Value, _Tag). 443pwp_attr(tag, Value, _Ask, _Use, _How, _Att, Value).

454pwp_attr(Atom, PWP) :- 455 atom(Atom), 456 atom_concat('pwp:', PWP, Atom), 457 !. 458pwp_attr('http://www.cs.otago.ac.nz/staffpriv/ok/pwp.pl':PWP, PWP) :- !. 459pwp_attr('pwp':PWP, PWP) :- !. 460pwp_attr('xmlns:pwp', -).

473pwp_unite(Bindings, Context0, Context) :- 474 pwp_unite(Bindings, Context0, Context0, Context). 475 476 477pwp_unite([], _, Context, Context). 478pwp_unite([Binding|Bindings], Context0, Context1, Context) :- 479 memberchk(Binding, Context0), 480 !, 481 pwp_unite(Bindings, Context0, Context1, Context). 482pwp_unite(['CONTEXT'=Context0|Bindings], Context0, Context1, Context) :- 483 !, 484 pwp_unite(Bindings, Context0, Context1, Context). 485pwp_unite([Binding|Bindings], Context0, Context1, Context) :- 486 pwp_unite(Bindings, Context0, [Binding|Context1], Context).

507pwp_unite([], _). 508pwp_unite([Binding|Bindings], Context) :- 509 memberchk(Binding, Context), 510 !, 511 pwp_unite(Bindings, Context). 512pwp_unite([_=Value|_], _) :- 513 functor(Value, _, _).

520pwp_attach([], Ys, Ys) :- !. 521pwp_attach([X|Xs], Ys0, Ys) :- 522 !, 523 pwp_attach(X, Ys0, Ys1), 524 pwp_attach(Xs, Ys1, Ys). 525pwp_attach(X, [X|Ys], Ys). 526 527 528 529pwp_element('-', _, Kids, Use, How, _, M, Context, Xml) :- 530 !, 531 pwp_use(Use, How, Kids, M, Context, Xml). 532pwp_element(Tag, Atts, [Value], Use, How, Magic, M, Context, 533 element(Tag,Atts1,Kids1)) :- 534 verbatim_element(Tag), nonvar(Magic), atomic(Value), 535 !,

540. 541pwp_element(Tag, Atts, Kids, Use, How, Magic, M, Context, 542 element(Tag,Atts1,Kids1)) :- 543 ( nonvar(Magic) 544 -> pwp_substitute(Atts, Magic, Context, Atts1) 545 ; Atts1 = Atts 546 ), 547 pwp_use(Use, How, Kids, M, Context, Kids1). 548 549pwp_use('', _, Kids, M, Context, Kids1) :- 550 !, 551 pwp_list(Kids, Kids1, M, Context). 552pwp_use(Use, How, _, M, Context, Kids1) :- 553 atom_to_term(Use, Term, Bindings), 554 pwp_unite(Bindings, Context), 555 pwp_how(How, Term, M, Context, Kids1). 556 557pwp_how('text', Term, _,_, [CData]) :- 558 !, 559 pwp_use_codes(Term, Codes, []), 560 atom_codes(CData, Codes). 561pwp_how('xml', Term, _,_, Kids1) :- 562 ( Term == [] -> Kids1 = Term 563 ; Term = [_|_] -> Kids1 = Term 564 ; Kids1 = [Term] 565 ). 566pwp_how('text-file', Term, _,_, [CData]) :- 567 pwp_use_codes(Term, Codes, []), 568 atom_codes(FileName, Codes), 569 read_file_to_codes(FileName, FileCodes, []), 570 atom_codes(CData, FileCodes). 571pwp_how('xml-file', Term, _,_, Kids1) :- 572 pwp_use_codes(Term, Codes, []), 573 atom_codes(FileName, Codes), 574 load_xml_file(FileName, Kids1). 575pwp_how('pwp-file', Term, M,Context, Kids1) :- 576 pwp_use_codes(Term, Codes, []), 577 atom_codes(FileName, Codes), 578 ( memberchk('SCRIPT_DIRECTORY'=ScriptDir,Context) -> true 579 ; ScriptDir='.' 580 ), 581 absolute_file_name(FileName, PathName, [relative_to(ScriptDir)]), 582 load_xml_file(PathName, Kids0), 583 pwp_xml(M:Kids0, Kids1, Context), 584 !. 585 586 587pwp_substitute([], _, _, []). 588pwp_substitute([AV|AVs], Magic, Context, NewAvs) :- 589 AV = (Name = Value), 590 ( sub_atom(Value, _, _, _, Magic) 591 -> char_code(Magic, C), 592 atom_codes(Value, Codes), 593 pwp_split(Codes, C, B0, T0, A0, Type), 594 !, 595 ( pwp_substitute(B0, T0, A0, C, Context, V, Type) 596 -> NewAvs = [AV1|Atts1], 597 atom_codes(New_Value, V), 598 AV1 = (Name = New_Value) 599 ; Type == existence-> 600 NewAvs = Atts1 601 ), 602 pwp_substitute(AVs, Magic, Context, Atts1) 603 ). 604pwp_substitute([AV|AVs], Magic, Context, [AV|Atts1]) :- 605 pwp_substitute(AVs, Magic, Context, Atts1). 606 607 608pwp_substitute(B0, T0, A0, C, Context, V0, Type) :- 609 append(B0, V1, V0), 610 atom_codes(Atom, T0), 611 atom_to_term(Atom, Term, Bindings), 612 pwp_unite(Bindings, Context, _), 613 ( Type == value 614 -> pwp_use_codes(Term, V1, V2) 615 ; catch(Term, _, fail), 616 V2 = V1 617 ), 618 ( pwp_split(A0, C, B1, T1, A1, T2) 619 -> pwp_substitute(B1, T1, A1, C, Context, V2, T2) 620 ; V2 = A0 621 ). 622 623 624pwp_split(Codes, C, Before, Text, After, Type) :- 625 append(Before, [C,C1|Rest], Codes), 626 ( C1 == 0'( 627 -> Type = value, 628 C2 = 0') 629 ; C1 == 0'[, 630 Type = existence, 631 C2 = 0'] 632 ), 633 append(Text, [C2,C|After], Rest), 634 !. 635 636pwp_use_codes(format(Format), S0, S) :- 637 !, 638 pwp_format(Format, [], S0, S). 639pwp_use_codes(format(Format,Args), S0, S) :- 640 !, 641 pwp_format(Format, Args, S0, S). 642pwp_use_codes(write_canonical(Datum), S0, S) :- 643 !, 644 pwp_format('~k', [Datum], S0, S). 645pwp_use_codes(print(Datum), S0, S) :- 646 !, 647 pwp_format('~p', [Datum], S0, S). 648pwp_use_codes(writeq(Datum), S0, S) :- 649 !, 650 pwp_format('~q', [Datum], S0, S). 651pwp_use_codes(write(Datum), S0, S) :- 652 !, 653 pwp_format('~w', [Datum], S0, S). 654pwp_use_codes(Atomic, S0, S) :- 655 atomic(Atomic), 656 !, 657 ( number(Atomic) -> number_codes(Atomic, Codes) 658 ; atom(Atomic) -> atom_codes(Atomic, Codes) 659 ; string(Atomic) -> string_codes(Atomic, Codes) 660 ; pwp_format('~w', [Atomic], S0, S) 661 ), 662 append(Codes, S, S0). 663pwp_use_codes([X|Xs], S0, S) :- 664 pwp_is_codes([X|Xs]), 665 !, 666 append([X|Xs], S, S0). 667pwp_use_codes([X|Xs], S0, S) :- 668 !, 669 pwp_use_codes(Xs, X, S0, S). 670pwp_use_codes(Compound, S0, S) :- 671 Compound =.. [_,X|Xs], 672 pwp_use_codes(Xs, X, S0, S). 673 674 675 676pwp_use_codes([], X, S0, S) :- 677 !, 678 pwp_use_codes(X, S0, S). 679pwp_use_codes([Y|Ys], X, S0, S) :- 680 pwp_use_codes(X, S0, S1), 681 pwp_use_codes(Ys, Y, S1, S).

694pwp_is_codes([]). 695pwp_is_codes([C|Cs]) :- 696 integer(C), C >= 0, C =< 0x10FFFF, 697 pwp_is_codes(Cs). 698 699pwp_format(Format, Arguments, S0, S) :- 700 format(codes(S0, S), Format, Arguments). 701 702 703verbatim_element(script). 704verbatim_element(style)