The Prolog class provides several methods for calling
Prolog from JavaScript.
String and returns
true or false. This simple calling pattern is
intended for trivial goals such as setting a Prolog flag. For example,
the call below limits the Prolog stacks to 10Mb.
Prolog.call("set_prolog_flag(stack_limit, 10 000 000)");
String, optionally binding
Prolog variables embedded in Goal from properties of the Object
Input. The returned object is an instance of class Query.
This instance can be used as a JavaScript iterator. The value
returned in each iteration is an Object with properties for
each variable in Goal that is not in Input and
does not start with an underscore. For example, we can iterate over the
members of a list like below. Further details on class Query
are provided in section
13.2.1. The translation of data between Prolog and JavaScript is
described in section
13.2.3.
for(let r of Prolog.query("member(Elem,List)",
{List: ["aap", "noot", "mies"]}))
{ console.log(r.Elem);
}
This interface is also practical for calling (fast) Prolog predicates
to compute a single answer from an input using the Query.once()
method. Assuming a Prolog predicate fib/2 that computes the nth Fibonacci
number, we can call this using the code below. Note that if the fib/2
fails or raises an exception the object returned by Query.once()
does not contain the
Out key and thus our function returns undefined.
function fib(in, out)
{ return Prolog.query("fib(In,Out)", {In:in}).once().Out;
}
The .query()
method is indented for fast queries that do not require the yield
mechanism, i.e., the execution should not require asynchronous
operations and the browser is not responsive during the execution. Use Prolog.forEach()
for asynchronous queries.
The optional Options parameter defines the following options
true, run the query in a temporary engine. Note that
JavaScript can only interact with the innermost query of an
engine. By using a new engine we can interact with multiple queries,
using them as coroutines. Prolog.Engine()
for details.string. Alternatively one may use atom.true, the execution cannot be seen in the
debugger.Function is called
with a Object that holds the bindings for the output
arguments of Goal for each answer. Options
supports the following options
true, create an engine that will be destroyed when the
query completes.
All default parameters may be omitted. A JavaScript type check is
used to discover whether the Input or OnAnswer
parameter is omitted. Use an empty Input to specify Options
without inputs, e.g. forEach(goal, {}, {engine:true})
The returned Promise is resolved when the query
completes. The value passed to the .then() method of
the Promise is the number of answers if OnAnswer
is provided or an Array of answers if OnAnswer
is omitted. If Goal raises an exception the Promise
is rejected.
Multiple calls to Prolog can be activated on the same engine at any
time. Prolog processes such queries in LIFO (Last In, First
Out) mode. If queries need to be processed sequentially use
JavaScript await or the Promise.finally()
method to wait for completion. Multiple Prolog.forEach()
queries that run in separate engines act as cooperative threads,
i.e., all make progress. For example, a goal can be started to run as
cooperative thread using:
setTimeout(async () => {
await Prolog.forEach(goal, input, onanswer,
{engine:true});
});
The method Prolog.query()
returns an instance of the JavaScript class Query that may
be used to explore the solutions of the query. The Query
class implements the JavaScript iterator protocol.
done and value. If exception
handling is enabled it returns an object
{done:true, error:true,
message:String}..value
of the object returned by .next() on success and the
complete object on failure or error. In addition, on a logical result
(no error), a field
success is added with a boolean value. Thus, the return
value may contain these keys:
success key is set to true.success:false}error:true, message:String}
The WASM version of SWI-Prolog supports engines. The initial
engine is called main. Additional engines can be used to
enumerate answers of multiple open queries as well as for implementing
coroutines. Combined with JavaScript async functions,
engines can provide cooperative multi-threading. For example,
to enumerate the answers of two queries we may use the following code
const e1 = new Prolog.Engine({auto_close:true});
const e2 = new Prolog.Engine({auto_close:true});
const q1 = e1.query(Query1); // see Prolog.query()
const q2 = e2.query(Query2);
try
{ for(;;)
{ const n1 = q1.next();
const n2 = q2.next();
if ( n1.done && n2.done )
break;
// Handle answers
}
} finally
{ q1.close(); // also closes e1
q2.close();
}
...
Engines can also be used to create a cooperative thread. The example below creates a Prolog task that prints the numbers 1..20 to the console, one number every second.
...
setTimeout(async () => {
const e = new Prolog.Engine({auto_close:true});
await e.forEach("between(1,20,X),sleep(1)",
(a) => console.out(a.X));
});
engineN, where N
is defined by a counter. The options argument provides
additional configuration. Both arguments are optional.
auto_closetrue (default false, closing the last
query associated with the engine also closes the engine.
JavaScript and Prolog are both dynamically typed languages. The WASM module defines a faithful translation between JavaScript data and Prolog data that aims at completeness as well as keeping the data representation clean in the common cases. We describe the translation in two descriptions because round tripping does not always result in the original object.
This section describes how data from JavaScript is translated into Prolog. The interface is primarily designed for passing JavaScript data as typically used to a natural Prolog representation. In addition a number of classes are provided to create Prolog specific data structures such as strings (as opposed to atoms), variables, compound terms, etc.
new Prolog.String(text)
to create a Prolog string. See below.true or false.undefined.null.$:Typev holds the text. May be
created using new Prolog.string(text). May be created using new
Prolog.String(text).n and d
represent the numerator and denominator. For example,
to represent 1r3, use {$:"r",
n:1, d:3}. May be created using new
Prolog.Rational(n, d), where n and d can be
JavaScript numbers or big integers.point(1,2) is constructed using
{$:"t", point:[1,2]}. May be created using new
Prolog.Compound(functor, args)v is present this
identifies the variable. Two variables processed in the same translation
with the same identifier represent the same Prolog variable. If the v
key is omitted the variable will be unique. May be created using new
Prolog.Var(id).Array we only need
this typed object to create a partial list. The v
key contains the “normal” elements and the key tail
contains the tail of the list. May be created using new
Prolog.List(array, tail).Objectdict.
Note that JavaScript object keys are always strings and (thus) all dict
keys are atoms. This, {1:"one"} is translated into
_{'1': one}.ArrayBuffer are translated into a Prolog
string that consists of characters in the range 0 ... 255.Object<js_Class(id)>. The
Prolog interface allows for passing the objects back and calling methods
on them. See section
13.3.
Most of the translation from Prolog data to JavaScript is the reverse
of the translation described in section
13.2.3.1. In some cases however reverse translation is ambiguous.
For example, both
42 and 42n (a JavaScript BigInt)
translate to a simple Prolog integer. The other way around, as
JavaScript
Number is a float, both Prolog 42 and 42.0
translate to 42 in JavaScript.
Prolog.Variable instance where
the identifier is a unique number of each unique variable.Number when possible or
BigInt otherwise. Currently JavaScript Number
can represent integers up to 2^53 precisely.Prolog.Rational instance.Number.String.Prolog.String instance.Array,
otherwise create a JavaScript Prolog.List instance.Prolog.Compound instance.Object with the same keys. If the
dict has a non-var tag, add a $tag property.