pengines - npm Package Compare versions
Comparing version 1.0.2 to 2.0.0
| { | ||
| "name": "pengines", | ||
| "version": "1.0.2", | ||
| "description": "The Node version of pengines.js - communicating with prolog engines", | ||
| "main": "lib/pengines", | ||
| "scripts": { | ||
| "test": "nodeunit --reporter verbose", | ||
| "prepublish": "coffee -o lib/ -c src/pengines.coffee" | ||
| }, | ||
| "devDependencies": { | ||
| "coffee-script": ">=1.9.1" | ||
| }, | ||
| "keywords": [ | ||
| "pengines", | ||
| "pengine", | ||
| "prolog", | ||
| "engine", | ||
| "rewrite" | ||
| ], | ||
| "author": "Karl Lundfall <kalle.lundfall@gmail.com>", | ||
| "license": "ISC", | ||
| "dependencies": { | ||
| "request": "^2.55.0", | ||
| "string": "^3.1.1" | ||
| }, | ||
| "bugs": { | ||
| "url": "https://gitlab.com/kll300/Pengines-for-node" | ||
| } | ||
| "name": "pengines", | ||
| "version": "2.0.0", | ||
| "dependencies": { | ||
| "najax": "^1.0.4" | ||
| }, | ||
| "devDependencies": { | ||
| "jquery": "^3.3.1", | ||
| "mocha": "^5.2.0", | ||
| "puppeteer": "^1.9.0" | ||
| }, | ||
| "main": "web/js/pengines.js", | ||
| "license": "BSD-2-Clause", | ||
| "bugs": { | ||
| "url": "https://github.com/SWI-Prolog/packages-pengines/issues" | ||
| }, | ||
| "files": [ | ||
| "web/js/pengines.js" | ||
| ] | ||
| } |
161
README.md
@@ -1,93 +0,120 @@ | ||
| Performing remote Prolog against a server can now be done also in Node. | ||
| # Pengines | ||
| ## Example | ||
| Pengines is short for Prolog Engines. The pengines package greatly | ||
| simplifies developing JavaScript based web-applications that must | ||
| talk to a Prolog server and realise distributed programming in | ||
| Prolog by providing RPC over HTTP. | ||
| ``` | ||
| peng = pengines( | ||
| server: "http://localhost:3020/pengine", | ||
| chunk: 2, | ||
| src_text: 'animal(cat).\n' + 'animal(dog).\n' | ||
| ask: 'animal(Animal)' | ||
| ) | ||
| .on 'success', (result) -> | ||
| for resultData in result.data | ||
| console.log resultData.Animal | ||
| ``` | ||
| ## The JavaScript API | ||
| output: | ||
| The Pengines JavaScript API allows a web application developer to create a pengine object like so: | ||
| ```js | ||
| var pengine = new Pengine(options); | ||
| ``` | ||
| cat | ||
| dog | ||
| ``` | ||
| ## Functionality | ||
| options is a JavaScript object contaning zero or more of | ||
| <dl> | ||
| <dt>server:string</dt> | ||
| <dd>A URL pointing to the Pengines server on which to create the pengine. Default is the server from which pengines.js is loaded.</dd> | ||
| <dt>application:string</dt> | ||
| <dd>The name of the application in which the pengine is to be run. Default is "pengine_sandbox".</dd> | ||
| <dt>ask:string</dt> | ||
| <dd>The query passed to the pengine immediately after its creation. By default no query is passed. Using this option will typically save one network roundtrip and thus using it with a deterministic query will result in just one roundtrip being made.</dd> | ||
| <dt>template:string</dt> | ||
| <dd>A Prolog variable (or a term containing Prolog variables) shared with the query. Meaningful only if the ask option is specified. By default the value of this option is the variable bindings of the query passed in the ask option (a list of Name=Var pairs). Variable names in the query starting with an underscore character will however not appear in the list.</dd> | ||
| <dt>chunk:integer</dt> | ||
| <dd>The maximum number of solutions to retrieve in one chunk. 1 means no chunking (default).</dd> | ||
| <dt>destroy:boolean</dt> | ||
| <dd>Determines if the pengine is to destroy itself after having run a query to completion. Defaults to true.</dd> | ||
| <dt>src:string</dt> | ||
| <dd>Prolog source code to be injected in the pengine before attempting to solve any queries.</dd> | ||
| <dt>format:string</dt> | ||
| <dd>Determines the format of event responses, default is json. New formats can be added by defining event_to_json/3. See library(pengines_io).</dd> | ||
| <dt>oncreate:function</dt> | ||
| <dd>JavaScript function to be called when a pengine has been created. The expression this.id in the scope of the function points to the id of the pengine.</dd> | ||
| <dt>onsuccess:function</dt> | ||
| <dd>Called when the pengine responds with a successful answer to a query. In the scope of the function the expression this.data points to a list of objects each representing a solution to the query, this.more evaluates to a boolean indicating whether more solutions may exist, andthis.id points to the id of the pengine returning the answer.</dd> | ||
| <dt>onfailure:function</dt> | ||
| <dd>Called when the pengine fails to find a solution. The expression this.id points to the id of the pengine reporting the failure.</dd> | ||
| <dt>onerror:function</dt> | ||
| <dd>Called when the pengine throws an error. The expression this.data in the scope of the function evaluates to an error message in the form of a string. The expression this.id points to the id of the pengine returning the error.</dd> | ||
| <dt>onprompt:function</dt> | ||
| <dd>Called when the pengine evaluates the pengine_input/2 predicate. The expression this.data in the scope of the function evaluates to a prompt in the form of a string or a JavaScript object. The expression this.id points to the id of the pengine producing the prompt.</dd> | ||
| <dt>onoutput:function</dt> | ||
| <dd>Called when the pengine has evaluated the built in pengine_output/1 predicate. The expression this.data in the scope of the function evaluates to a string or a JavaScript object. The expression this.id points to the id of the pengine generating the output.</dd> | ||
| <dt>onstop:function</dt> | ||
| <dd>Called when a running query has been successfully stopped. The expression this.id points to the id of the pengine having been stopped.</dd> | ||
| <dt>onabort:function</dt> | ||
| <dd>Called when a running query has been successfully aborted. The expression this.id points to the id of the pengine having been aborted.</dd> | ||
| <dt>ondestroy:function</dt> | ||
| <dd>Called when the pengine has been successfully destroyed. The expression this.id points to the id of the pengine having been destroyed.</dd> | ||
| </dl> | ||
| ### pengines(options) | ||
| A pengine object also provides access to the following fields and methods. | ||
| Constructs a pengine. Options: | ||
| <dl> | ||
| <dt>pengine.id</dt> | ||
| <dd>Evaluates to the id of the pengine (a string). Note that the pengine must have been created before this field will have a non-null value, i.e. the oncreate handler must have been called.</dd> | ||
| <dt>pengine.ask(query, options)</dt> | ||
| <dd>Runs query in search for the first solution. Throws an error if the query is syntactically or semantically malformed or if running it could compromise the safety of the server. options is a JavaScript object contaning zero or more of | ||
| <dl> | ||
| <dt>template: string</dt> | ||
| <dd>A Prolog variable (or a term containing Prolog variables) shared with the query. Meaningful only if the ask option is specified. By default the value of this option is the variable bindings of the query passed in the ask option (a list of Name=Var pairs). Variable names in the query starting with an underscore character will however not appear in the list.</dd> | ||
| <dt>chunk: integer</dt> | ||
| <dd>The maximum number of solutions to retrieve in one chunk. 1 means no chunking (default).</dd> | ||
| </dt> | ||
| </dd> | ||
| <dt>pengine.next()</dt> | ||
| <dd>Triggers a search for the next solution.</dd> | ||
| <dt>pengine.stop()</dt> | ||
| <dd>Stops searching for solutions. Terminates the running query gracefully.</dd> | ||
| <dt>pengine.respond(string or object)</dt> | ||
| <dd>Inputs a term in response to a prompt from an invocation of pengine_input/2 that is now waiting to receive data from the outside. Throws an error if string cannot be parsed as a Prolog term or if object cannot be serialised into JSON.</dd> | ||
| <dt>pengine.abort()</dt> | ||
| <dd>Terminates the running query by force.</dd> | ||
| <dt>pengine.destroy()</dt> | ||
| <dd>Destroys the pengine.</dd> | ||
| </dl> | ||
| - `server` - A URL pointing to the Pengines server on which to create the pengine. | ||
| - `application` - The name of the application in which the pengine is to be run. Default is `swish`. | ||
| - `ask` - The query passed to the pengine immediately after its creation. By default no query is passed. Using this option will typically save one network roundtrip and thus using it with a deterministic query will result in just one roundtrip being made. | ||
| - `template`- A Prolog variable (or a term containing Prolog variables) shared with the query. Meaningful only if the ask option is specified. By default the value of this option is the variable bindings of the query passed in the ask option (a list of Name=Var pairs). Variable names in the query starting with an underscore character will however not appear in the list. | ||
| - `chunk`- The maximum number of solutions to retrieve in one chunk. 1 means no chunking (default). | ||
| - `destroy`- Determines if the pengine is to destroy itself after having run a query to completion. Defaults to `true`. | ||
| - `sourceText` - Prolog source code to be injected in the pengine before attempting to solve any queries. | ||
| - `format` - Determines the format of event responses. Can be one of the following options: | ||
| * `json` (default) | ||
| * `json-s` | ||
| * `json-html` | ||
| * New formats can be added by defining `event_to_json/3`. See `library(pengines_io)`. | ||
| - `cookieJar`- An instance of a jar containing cookies which will be used in the queries, usually retreived from the [request.jar()](https://github.com/request/request#requestjar). | ||
| ## Examples | ||
| Please refer to documentation at [here][documentation] for working examples. | ||
| ### on(event,function) | ||
| [documentation]:http://www.swi-prolog.org/pldoc/man?section=pengine-overview | ||
| Make `function` trigger on `event`. Supported values of `event` are: | ||
| ## The Prolog API | ||
| - `create` - The pengine has been created. | ||
| - `success` - The pengine responds with a successful answer to a query. The callback is an object containing the following fields: | ||
| * `data` - A list of objects each representing a solution to the query, | ||
| * `more` - A boolean indicating whether more solutions may exist | ||
| * `id `- The id of the pengine returning the answer. | ||
| - `error` - The pengine throws an error. The expression this.data in the scope of the function evaluates to an error message in the form of a string. | ||
| - `prompt` - The pengine evaluates the `pengine_input/2` predicate. The expression this.data in the scope of the function evaluates to a prompt in the form of a string or an object. | ||
| - `failure` - The pengine fails to find a solution. | ||
| - `stop` - A running query has been successfully stopped. | ||
| - `abort` - A running query has been successfully aborted. | ||
| - `destroy` - The pengine has been successfully destroyed. | ||
| The Prolog API is documented in the following document: [Prolog API][prolog-api]. | ||
| ### ask(expression) | ||
| [prolog-api]:http://www.swi-prolog.org/pldoc/man?section=pengine-libs | ||
| Forwards a Prolog expression to the server. | ||
| ## Usage in Node.js | ||
| ### next() | ||
| Install using NPM: `npm install pengines` and use: | ||
| Asks the pengine for the next solution from last asked expression. | ||
| ```js | ||
| var Pengine = require('pengines'); | ||
| var pengine = new Pengine(); | ||
| ``` | ||
| and follow the JavaScript API description above. | ||
| ### abort() | ||
| ## Testing | ||
| Terminates the running query by force. | ||
| To test the Pengines JavaScript API, you need to install required | ||
| testing dependencies using the `npm install` command in the | ||
| project root directory. | ||
| ### destroy() | ||
| Then load `test_js.pl` in SWI-Prolog: | ||
| Destroys the pengine. | ||
| ``` | ||
| -? [test_js]. | ||
| ``` | ||
| ### respond(item) | ||
| and run tests using `run_tests`. | ||
| Inputs a term in response to a prompt from an invocation of `pengine_input/2` that is now waiting to receive data from the outside. Generates an error if string cannot be parsed as a Prolog term or if object cannot be serialised into JSON. | ||
| ## License | ||
| ### stop() | ||
| Stops the query currently running without destroying the object. | ||
| ## Set it off! | ||
| ```npm install pengines``` | ||
| ## Credits | ||
| Modified version of [pengines.js](http://swish.swi-prolog.org/pengine/pengines.js), developed by Torbjörn Lager. Most options and events are identical to as documented in [this version](http://pengines.swi-prolog.org/docs/documentation.html). For more information on the application flow, see [this resource](http://www.swi-prolog.org/pldoc/man?section=pengine-overview). | ||
| Pengines is licensed under the BSD 2-Clause license. See the header of web/js/pengines.js file. |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
New author
Supply chain riskA new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.
Found 1 instance in 1 package
No contributors or author data
MaintenancePackage does not specify a list of contributors or an author in package.json.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Dependency count
- decreased by-50%
1
- Lines of code
- increased by72.78%
603
- Number of lines in readme file
- increased by28.72%
121
Worsened metrics
- Total package byte prevSize
- decreased by-14.81%
26475
- Dev dependency count
- increased by200%
3
- Number of package files
- decreased by-57.14%
3
- Number of low maintenance alerts
- increased by100%
2
- Number of medium supply chain risk alerts
- increased byInfinity%
2
Dependency changes
+ Addednajax@^1.0.4
+ Addedcall-bind@1.0.7(transitive)
+ Addeddefine-data-property@1.1.4(transitive)
+ Addedes-define-property@1.0.0(transitive)
+ Addedes-errors@1.3.0(transitive)
+ Addedfunction-bind@1.1.2(transitive)
+ Addedget-intrinsic@1.2.4(transitive)
+ Addedgopd@1.0.1(transitive)
+ Addedhas-property-descriptors@1.0.2(transitive)
+ Addedhas-proto@1.0.3(transitive)
+ Addedhas-symbols@1.0.3(transitive)
+ Addedhasown@2.0.2(transitive)
+ Addedjquery-deferred@0.3.1(transitive)
+ Addedlodash@4.17.21(transitive)
+ Addednajax@1.0.7(transitive)
+ Addedobject-inspect@1.13.3(transitive)
+ Addedqs@6.13.0(transitive)
+ Addedset-function-length@1.2.2(transitive)
+ Addedside-channel@1.0.6(transitive)
- Removedrequest@^2.55.0
- Removedstring@^3.1.1
- Removedajv@6.12.6(transitive)
- Removedasn1@0.2.6(transitive)
- Removedassert-plus@1.0.0(transitive)
- Removedasynckit@0.4.0(transitive)
- Removedaws-sign2@0.7.0(transitive)
- Removedaws4@1.13.2(transitive)
- Removedbcrypt-pbkdf@1.0.2(transitive)
- Removedcaseless@0.12.0(transitive)
- Removedcombined-stream@1.0.8(transitive)
- Removedcore-util-is@1.0.2(transitive)
- Removeddashdash@1.14.1(transitive)
- Removeddelayed-stream@1.0.0(transitive)
- Removedecc-jsbn@0.1.2(transitive)
- Removedextend@3.0.2(transitive)
- Removedextsprintf@1.3.0(transitive)
- Removedfast-deep-equal@3.1.3(transitive)
- Removedfast-json-stable-stringify@2.1.0(transitive)
- Removedforever-agent@0.6.1(transitive)
- Removedform-data@2.3.3(transitive)
- Removedgetpass@0.1.7(transitive)
- Removedhar-schema@2.0.0(transitive)
- Removedhar-validator@5.1.5(transitive)
- Removedhttp-signature@1.2.0(transitive)
- Removedis-typedarray@1.0.0(transitive)
- Removedisstream@0.1.2(transitive)
- Removedjsbn@0.1.1(transitive)
- Removedjson-schema@0.4.0(transitive)
- Removedjson-schema-traverse@0.4.1(transitive)
- Removedjson-stringify-safe@5.0.1(transitive)
- Removedjsprim@1.4.2(transitive)
- Removedmime-db@1.52.0(transitive)
- Removedmime-types@2.1.35(transitive)
- Removedoauth-sign@0.9.0(transitive)
- Removedperformance-now@2.1.0(transitive)
- Removedpsl@1.10.0(transitive)
- Removedpunycode@2.3.1(transitive)
- Removedqs@6.5.3(transitive)
- Removedrequest@2.88.2(transitive)
- Removedsafe-buffer@5.2.1(transitive)
- Removedsafer-buffer@2.1.2(transitive)
- Removedsshpk@1.18.0(transitive)
- Removedstring@3.3.3(transitive)
- Removedtough-cookie@2.5.0(transitive)
- Removedtunnel-agent@0.6.0(transitive)
- Removedtweetnacl@0.14.5(transitive)
- Removeduri-js@4.4.1(transitive)
- Removeduuid@3.4.0(transitive)
- Removedverror@1.10.0(transitive)