clingojs

A Node.js wrapper module for the Clingo program.

npm install clingojs

This module requires Clingo to be installed to work. Tested with Clingo 4.2.1 but likely works with other versions as well.

Basic Usage

var Clingo = require('clingo');

var clingo = new Clingo();

clingo.config({ // Sets the basic configuration for this clingo instance
	maxModels: 0 // Return all models
});

clingo.solve({
	inputFiles: ['/path/to/some/file']
})
	.on('model', function(model) {
		// Here 'model' is an Array of strings representing the atoms of the model
		// e.g. ['example(0)', 'example(1)']
	})
	.on('end', function() {
		// This function gets called after all models have been received
	});

Class: Clingo

Clingo([options])

The Clingo constructor takes an optional options argument containing configuration options detailed in the Configuration section.

clingo.config([options])

If options argument is present, merges the options object into the configuration of this clingo instance and returns the instance.

If options is missing, returns the configuration object of this clingo instance.

clingo.setConfig(config)

Completely replaces this instance's configuration object with config.

clingo.solve([options])

Starts the Clingo process. The process uses the instance's configuration, in addition to any other configurations passed in the options argument. Note: Any configurations passed in options do not last beyond the solve() function.

Returns an object of the form { on: [Function] }. See the Basic Usage section for an example.

Configuration

The following sections document the different options that can be passed to the config(), setConfig(), and solve() functions.

clingo

A string which specifies the clingo command. May be a full path, or just the name of the executable if it is on the environment's path.

var clingo = new Clingo({
	clingo: '/usr/bin/clingo'
});

Default: 'clingo'

maxModels

The maximum number of models to find. If maxModels is 0 then all models are found.

var clingo = new Clingo({
	maxModels: 0
});

Default: 1

constants

An object to specify clingo constants. This uses the clingo '-c' argument.

var clingo = new Clingo({
	constants: { foo: 0, bar = 1 } // The same as passing '-c foo=0,bar=1' on the command line
});

Default: {}

inputFiles

An array of input files for the clingo process to read in. These files should be written using gringo syntax.

var clingo = new Clingo({
	inputFiles: ['/path/to/file', '/path/to/otherFile']
});

Default: []

input

The input config property defines input which is to be written to the process' stdin when solve() is called. It can be one of the following:

• string: A string is written as it appears to stdin.
• Array: An Array will be interpreted as atoms, the written to stdin. For example, the array ['example(0)', 'example(1)'] will be written as 'example(0). example(1).'
• Readable stream: A Readable stream will be piped to stdin.
• Object: Any other object not listed above will have the output of its toString() written to stdin.

var clingo = new Clingo({
	input: 'tobe | not tobe.'
});

Default: undefined

args

Defines any additional arguments to start the clingo process with.

var clingo = new Clingo({
	args: ['--time-limit=10']
});

Default: []

returnStdin

When set to true, the clingo process' stdin will be left open to be further written to. When solve() is invoked, the returned object will then have a stdin property which is a Writable stream. Don't forget to call stdin.end() or the process will not exit.

var clingo = new Clingo({
	returnStdin: true
})

var ps = clingo.solve({
	//... options
});

ps.stdin.write('I can write more to the process stdin!');
ps.stdin.end();

Default: false

returnStdout

When set to true, this bypasses the module's own interpreting of the process output, and instead returns the process stdout as a property of the object returned from solve().

var clingo = new Clingo({
	returnStdout: true
})

var ps = clingo.solve({
	//... options
});

ps.stdout.setEncoding('utf8');
ps.stdout.on('data', function(data) {
	// This is where you would read the process output directly
});
ps.stdout.on('end', function() {
	// Called when the output has been fully read
})

Default: false