Repository files navigation

A Node.js interface to the SWI-Prolog.

You need to have SWI-Prolog installed andswipl binary available inPATH and compiler installed. See "Platform support" for operating systemsupport. The library requires Node.js version 7+ and SWI-Prolog 8+.

npm install swipl

Also see "Known issues" for currently unsolved problems.

Calling a predicate and returning bindings withthe first solution:

constswipl=require('swipl');constret=swipl.call('member(X, [1,2,3,4])');if(ret){console.log(`Variable X value is:${ret.X}`);}else{console.log('Call failed.');}

Outputs:

Variable X value is: 1

Calling a predicate and returning all solutions:

constswipl=require('swipl');constquery=newswipl.Query('member(X, [1,2,3,4])');letret=null;while(ret=query.next()){console.log(`Variable X value is:${ret.X}`);}

Outputs:

Variable X value is: 1Variable X value is: 2Variable X value is: 3Variable X value is: 4

There can be only one query open at a time.

Use module operator: to call code in differentmodules. The default call assumes theuser module.

swipl.call('assert(mymodule:test(1))');console.log(swipl.call('mymodule:test(X)'));

Load code from external files. You might haveto set the working directory if you want to use relative paths.

swipl.call('working_directory(_, prolog)');swipl.call('consult(mycode)');

Queries with data requiring proper escaping can be constructedby using helper functions from swipl.term.

Example:

constswipl=require('./');const{ list, compound, variable, serialize}=swipl.term;constescaped=serialize(compound('member',[variable('X'),list([1,2,3,4])]));console.log(swipl.call(escaped));

Blobs and dicts are not supported.

Prolog terms in variable bindings are converted intoJavaScript objects under the following rules:

• Integers are converted to numbers.
• Floats are converted to numbers.
• Atoms and strings are converted to strings.
• Empty list is converted to string[].
• List head tail pair is converted to object{ head, tail } wherehead andtail are converted terms.
• Compound term is converted to object{ name, args } wherename is the compound functor name andargs is the arrayof converted argument terms.
• Blobs and dicts are not supported and will throw an error.

Syntax errors in queries are thrown. Error messagesare read from the prolog. The current query is automaticallyclosed.

Invalid query example:member(X, [1,2,3,4] (missing closing paren):

swipl.call('member(X, [1,2,3,4]');

Throws error with message:

Error: Error during query execution. Syntax error:Operator expectedmember(X, 1,2,3,4** here **

Known errors are thrown with the error message.

swipl.call('error:must_be(ground, _)');

Throws error with message:

Error: Error during query execution. Arguments arenot sufficiently instantiated.

Custom errors without a message are thrown with JavaScripterror containing the error term:

swipl.call('throw(error(test))');

Throws error with message:

Error: Error during query execution. Unknown message: error(test).

The embedded SWI-Prolog engine is automatically initializedwhen creating the first query. This behavior can be disabledby callingswipl.autoInitialise(false) before any query isexecuted. The engine can be initialized later manually withtheswipl.initialise() function.

The bindings are tested on various Linux distributions, on Windows,and on MacOS. SWI-Prolog commandswipl must be available inPATHon all of these operating systems.

Microsoft build tools must be installed:

npm install --global --production windows-build-tools

SWI-Prolog commandswipl must be available inPATH.

SWI-Prolog must be installed or compiled through Macports. This isdescribed herehttp://www.swi-prolog.org/build/macos.html. The setup wastested on MacOS Sierra by installing dependencies from ports and compilingwith prefix/usr/local (adjustbuild.templ).

• Unicode data cannot be exchanged.
• Exporting PL_BLOB terms is not handled.
• Exporting PL_DICT terms is not supported. It is not supported at all by SWI-Prologforeign interface.
• Installed files cannot be copied around on *nix. The linker haslibswipl locationspecified absolutely in the binding object file. The location ofSWI_HOME_DIR isdetermined install-time and written into the fileplbase.conf.
• Attempt to use native SWI packages leads to symbol lookup errorslikereadutil.so: undefined symbol: PL_new_atom.
• Custom initialization parameters are not yet implemented.

A list of helpful resources:

• SWI-Prolog Foreign Interface documentation:http://www.swi-prolog.org/pldoc/man?section=foreign
• Node.js native addons:https://nodejs.org/api/addons.html
• PySWIP sources:https://code.google.com/archive/p/pyswip/

• Pengines package.
• Packageswipl-stdio.
• Run SWI as HTTP server and create a JSON API.

Please see the AUTHORS file.

Licensed under LGPL 3.0. A copy is available inthe LICENSE.txt file.Filelib/serialize_string.js is ported from thepengines project and is licensedunder BSD (see the file header).