3.24 library(http/http_pwp): Serve PWP pages through the HTTP server

To be done

- Support elements in the HTML header that allow controlling the page, such as setting the CGI-header, authorization, etc.
- Allow external styling. Pass through reply_html_page/2? Allow filtering the DOM before/after PWP?

This module provides convience predicates to include PWP (Prolog Well-formed Pages) in a Prolog web-server. It provides the following predicates:

pwp_handler / 2

This is a complete web-server aimed at serving static pages, some of which include PWP. This API is intended to allow for programming the web-server from a hierarchy of pwp files, prolog files and static web-pages.

reply_pwp_page / 3

Return a single PWP page that is executed in the context of the calling module. This API is intended for individual pages that include so much text that generating from Prolog is undesirable.

pwp_handler(+Options, +Request)

Handle PWP files. This predicate is defined to create a simple HTTP server from a hierarchy of PWP, HTML and other files. The interface is kept compatible with the library(http/http_dispatch). In the typical usage scenario, one needs to define an http location and a file-search path that is used as the root of the server. E.g., the following declarations create a self-contained web-server for files in /web/pwp/.

user:file_search_path(pwp, '/web/pwp').

:- http_handler(root(.), pwp_handler([path_alias(pwp)]), [prefix]).

Options include:

path_alias(+Alias)

Search for PWP files as Alias(Path). See absolute_file_name/3.

index(+Index)

Name of the directory index (pwp) file. This option may appear multiple times. If no such option is provided, pwp_handler/2 looks for index.pwp.

view(+Boolean)

If true (default is false), allow for ?view=source to serve PWP file as source.

index_hook(:Hook)

If a directory has no index-file, pwp_handler/2 calls Hook(PhysicalDir, Options, Request). If this semidet predicate succeeds, the request is considered handled.

hide_extensions(+List)

Hide files of the given extensions. The default is to hide .pl files.

dtd(?DTD)

DTD to parse the input file with. If unbound, the generated DTD is returned

Errors

permission_error(index, http_location, Location) is raised if the handler resolves to a directory that has no index.

See also

reply_pwp_page/3

reply_pwp_page(:File, +Options, +Request)

Reply a PWP file. This interface is provided to server individual locations from PWP files. Using a PWP file rather than generating the page from Prolog may be desirable because the page contains a lot of text (which is cumbersome to generate from Prolog) or because the maintainer is not familiar with Prolog.

Options supported are:

mime_type(+Type)

Serve the file using the given mime-type. Default is text/html.

unsafe(+Boolean)

Passed to http_safe_file/2 to check for unsafe paths.

pwp_module(+Boolean)

If true, (default false), process the PWP file in a module constructed from its canonical absolute path. Otherwise, the PWP file is processed in the calling module.

Initial context:

SCRIPT_NAME

Virtual path of the script.

SCRIPT_DIRECTORY

Physical directory where the script lives

QUERY

Var=Value list representing the query-parameters

REMOTE_USER

If access has been authenticated, this is the authenticated user.

REQUEST_METHOD

One of get, post, put or head

CONTENT_TYPE

Content-type provided with HTTP POST and PUT requests

CONTENT_LENGTH

Content-length provided with HTTP POST and PUT requests

While processing the script, the file-search-path pwp includes the current location of the script. I.e., the following will find myprolog in the same directory as where the PWP file resides.

pwp:ask="ensure_loaded(pwp(myprolog))"

See also

pwp_handler/2.

To be done

complete the initial context, as far as possible from CGI variables. See http://hoohoo.ncsa.illinois.edu/docs/cgi/env.html