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

 js_script(+Content)// is det

Generate a JavaScript script element with the given content.

 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.

 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)
         ]),

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

 js_arg_list(+Expressions:list)// is det

Write javascript (function) arguments. This writes "(", Arg, ..., ")". See js_expression//1 for valid argument values.

 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.

 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.

 js_quoted_string(+Raw, -Quoted)[private]

Quote text for use in JavaScript. Quoted does not include the leading and trailing quotes.

To be done

- Join with json stuff.

 js_identifier(+Id:atom)// is det[private]

Emit an identifier if it is a valid one

 js_identifier(+Id:atom) is semidet[private]

True if Id is a valid identifier. In traditional JavaScript, this means it starts with [$_:letter:] and is followed by [$_:letter:digit:]

 json_to_string(+JSONTerm, -String)[private]

Write JSONTerm to String.

Undocumented predicates

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

 js_args(Arg1, Arg2, Arg3)