pengines_io.pl -- Provide Prolog I/O for HTML clients
This module redefines some of the standard Prolog I/O predicates to behave transparently for HTML clients. It provides two ways to redefine the standard predicates: using goal_expansion/2 and by redefining the system predicates using redefine_system_predicate/1. The latter is the preferred route because it gives a more predictable trace to the user and works regardless of the use of other expansion and meta-calling.
Redefining works by redefining the system predicates in the context of the pengine's module. This is configured using the following code snippet.
:- pengine_application(myapp). :- use_module(myapp:library(pengines_io)). pengines:prepare_module(Module, myapp, _Options) :- pengines_io:pengine_bind_io_to_html(Module).
Using goal_expansion/2 works by rewriting the corresponding goals using goal_expansion/2 and use the new definition to re-route I/O via pengine_input/2 and pengine_output/1. A pengine application is prepared for using this module with the following code:
:- pengine_application(myapp). :- use_module(myapp:library(pengines_io)). myapp:goal_expansion(In,Out) :- pengine_io_goal_expansion(In, Out).
- pengine_writeln(+Term)
- Emit Term as <span class=writeln>Term<br></span>.
- pengine_nl
- Emit a <br/> to the pengine.
- pengine_flush_output
- No-op. Pengines do not use output buffering (maybe they should though).
- pengine_write_term(+Term, +Options)
- Writes term as <span class=Class>Term</span>. In addition to the
options of write_term/2, these options are processed:
- class(+Class)
- Specifies the class of the element. Default is
write
.
- pengine_write(+Term) is det
- pengine_writeq(+Term) is det
- pengine_display(+Term) is det
- pengine_print(+Term) is det
- pengine_write_canonical(+Term) is det
- Redirect the corresponding Prolog output predicates.
- pengine_format(+Format) is det
- pengine_format(+Format, +Args) is det
- As format/1,2. Emits a series of strings with <br/> for each newline encountered in the string.
- pengine_listing is det
- pengine_listing(+Spec) is det
- List the content of the current pengine or a specified predicate in the pengine.
- user:message_hook(+Term, +Kind, +Lines) is semidet[multifile]
- Send output from print_message/2 to the pengine. Messages are embedded in a <pre class=msg-Kind></pre> environment.
- pengines:event_to_json(+Event, -JSON, +Format, +VarNames) is semidet[multifile]
- Provide additional translations for Prolog terms to output.
Defines formats are:
- json-s
- Simple or string format: Prolog terms are sent using quoted write.
- json-html
- Serialize responses as HTML string. This is intended for
applications that emulate the Prolog toplevel. This format
carries the following data:
- data
- List if answers, where each answer is an object with
- variables
- Array of objects, each describing a variable. These
objects contain these fields:
- variables: Array of strings holding variable names
- value: HTML-ified value of the variables
- substitutions: Array of objects for substitutions
that break cycles holding:
- var: Name of the inserted variable
- value: HTML-ified value
- residuals
- Array of strings representing HTML-ified residual goals.
- pengines:event_to_json(+PrologEvent, -JSONEvent, +Format, +VarNames)[multifile]
- If Format equals
'json-s'
or'json-html'
, emit a simplified JSON representation of the data, suitable for notably SWISH. This deals with Prolog answers and output messages. If a message originates from print_message/3, it gets several additional properties:- message:Kind
- Indicate the kind of the message (
error
,warning
, etc.) - location:_{ch:CharPos,file:File,line:Line}
- If the message is related to a source location, indicate the file and line and, if available, the character location.
- pengines:event_to_json(+Event, -JSON, +Format, +VarNames)[multifile]
- Implement translation of a Pengine event to
json-html
format. This format represents the answer as JSON, but the variable bindings are (structured) HTML strings rather than JSON objects.CHR residual goals are not bound to the projection variables. We hacked a bypass to fetch these by returning them in a variable named Residuals, which must be bound to a term '$residuals'(List). Such a variable is removed from the projection and added to residual goals.
- binding_term(+Term, +Vars, +WriteOptions)// is semidet[multifile]
- Hook to render a Prolog result term as HTML. This hook is called for each non-variable binding, passing the binding value as Term, the names of the variables as Vars and a list of options for write_term/3. If the hook fails, term//2 is called.
- pengine_io_predicate(?Head)
- True when Head describes the head of a (system) IO predicate that is redefined by the HTML binding.
- pengine_bind_io_to_html(+Module)
- Redefine the built-in predicates for IO to send HTML messages using pengine_output/1.
- pengine_write(+Term) is det
- pengine_writeq(+Term) is det
- pengine_display(+Term) is det
- pengine_print(+Term) is det
- pengine_write_canonical(+Term) is det
- Redirect the corresponding Prolog output predicates.
- pengine_write(+Term) is det
- pengine_writeq(+Term) is det
- pengine_display(+Term) is det
- pengine_print(+Term) is det
- pengine_write_canonical(+Term) is det
- Redirect the corresponding Prolog output predicates.
- pengine_write(+Term) is det
- pengine_writeq(+Term) is det
- pengine_display(+Term) is det
- pengine_print(+Term) is det
- pengine_write_canonical(+Term) is det
- Redirect the corresponding Prolog output predicates.
- pengine_write(+Term) is det
- pengine_writeq(+Term) is det
- pengine_display(+Term) is det
- pengine_print(+Term) is det
- pengine_write_canonical(+Term) is det
- Redirect the corresponding Prolog output predicates.
- pengine_format(+Format) is det
- pengine_format(+Format, +Args) is det
- As format/1,2. Emits a series of strings with <br/> for each newline encountered in the string.
- pengine_listing is det
- pengine_listing(+Spec) is det
- List the content of the current pengine or a specified predicate in the pengine.
Undocumented predicates
The following predicates are exported, but not or incorrectly documented.