PublicShow sourcejs_write.pl -- Utilities for including JavaScript

This library is a supplement to library(http/html_write) for producing JavaScript fragments. Its main role is to be able to call JavaScript functions with valid arguments constructed from Prolog data. For example, suppose you want to call a JavaScript functions to process a list of names represented as Prolog atoms. This can be done using the call below, while without this library you would have to be careful to properly escape special characters.

numbers_script(Names) -->
    html(script(type('text/javascript'),
         [ \js_call('ProcessNumbers'(Names)
         ]),

The accepted arguments are described with js_expression//1.

Source js_script(+Content)// is det
Generate a JavaScript script element with the given content.
Source javascript(+Content, +Vars, +VarDict, -DOM) is det
Quasi quotation parser for JavaScript that allows for embedding Prolog variables to substitude identifiers in the JavaScript snippet. Parameterizing a JavaScript string is achieved using the JavaScript + operator, which results in concatenation at the client side.
    ...,
    js_script({|javascript(Id, Config)||
                $(document).ready(function() {
                   $("#"+Id).tagit(Config);
                 });
               |}),
    ...

The current implementation tokenizes the JavaScript input and yields syntax errors on unterminated comments, strings, etc. No further parsing is implemented, which makes it possible to produce syntactically incorrect and partial JavaScript. Future versions are likely to include a full parser, generating syntax errors.

The parser produces a term \List, which is suitable for js_script//1 and html//1. Embedded variables are mapped to \js_expression(Var), while the remaining text is mapped to atoms.

To be done
- Implement a full JavaScript parser. Users should not rely on the ability to generate partial JavaScript snippets.
Source js_call(+Term)// is det
Emit a call to a Javascript function. The Prolog functor is the name of the function. The arguments are converted from Prolog to JavaScript using js_arg_list//1. Please not that Prolog functors can be quoted atom and thus the following is legal:
    ...
    html(script(type('text/javascript'),
         [ \js_call('x.y.z'(hello, 42))
         ]),
Source js_new(+Id, +Term)// is det
Emit a call to a Javascript object declaration. This is the same as:
['var ', Id, ' = new ', \js_call(Term)]
Source js_arg_list(+Expressions:list)// is det
Write javascript (function) arguments. This writes "(", Arg, ..., ")". See js_expression//1 for valid argument values.
Source js_expression(+Expression)// is det
Emit a single JSON argument. Expression is one of:
Variable
Emitted as Javascript null
List
Produces a Javascript list, where each element is processed by this library.
object(Attributes)
Where Attributes is a Key-Value list where each pair can be written as Key-Value, Key=Value or Key(Value), accomodating all common constructs for this used in Prolog. $ { K:V, ... } Same as object(Attributes), providing a more JavaScript-like syntax. This may be useful if the object appears literally in the source-code, but is generally less friendlyto produce as a result from a computation.
Dict
Emit a dict as a JSON object using json_write_dict/3.
json(Term)
Emits a term using json_write/3.
@(Atom)
Emits these constants without quotes. Normally used for the symbols true, false and null, but can also be use for emitting JavaScript symbols (i.e. function- or variable names).
Number
Emited literally
symbol(Atom)
Synonym for @(Atom). Deprecated.
Atom or String
Emitted as quoted JavaScript string.
Source js_arg(+Expression)// is semidet
Same as js_expression//1, but fails if Expression is invalid, where js_expression//1 raises an error.
deprecated
- New code should use js_expression//1.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

Source js_args(Arg1, Arg2, Arg3)