Application Programming Interface
Command line, RESTful and JavaScript APIs that integrate NETS into systems.
NETS has two kinds of API - application APIs and library APIs. Application APIs help to run NETS on the command line, as a web service or from JavaScript. Library APIs allow compiled grammars to be built using a set of C library functions. This section deals with application APIs.
Command Line Interface
The NETS Command Line Interface (CLI) allows the parser to be executed from an operating system terminal. It can be executed independently
or as part of a script or batch process. The nets-parser
command is followed by a number of command line parameters as follows.
These parameters are by convention used in the RESTful API and the JavaScript API.
The command line is called either as a native executable (MacOS/Linux/Windows, NodeJS WASM executable or a Wasmtime WASI executable.
Name | Command |
---|---|
Native Executable |
NETS is started from the command line by invoking the
For example |
NodeJS Executable |
NETS requires
NETS Command line arguments are added after the double dash |
Wasmtime Executable | NETS requires
|
Command line arguments are specified using either the -
or /
character followed
by the name of the parameter and followed optionally by an equal sign and the value of the paramater.
Name | Description |
---|---|
input |
Defines the input file for the parser. Defaults to default.in . |
output |
Defines the output file for the parser. Defaults to default.out . |
error |
Defines the log file for the parser. Defaults to default.log . |
loglevel |
Sets the initial loglevel for the parser. |
grammar |
Defines the grammars for the parser. Defaults to default.g . May include multiple
files separated by either '#' or ';' . |
grammar_xml |
Defines the grammar XML output file for the parser. Defaults to default.g.xml . |
nologo |
Ommits the copyright and version information from being displayed. |
encoding |
The input and output stream encoding in the form encoding="SOURCE/TARGET" . The default encoding is "ASCII/ASCII" . |
grammar_encoding |
The grammar encoding in the form encoding="SOURCE/TARGET" . The default grammar encoding is "ASCII/ASCII" . |
loadenv |
Load the system environment variables as context grammar entities. |
grammar_libpath |
Load path for compiled grammar libraries and the 'command.g' grammar. (Not used in cloud environments for security reasons). |
init |
Initialise the parser only and do not start. Can be used to check for configuration errors. |
help |
Displays help information about command line parameters. |
jobid |
The 'jobid' command line parameter adds jobid (instead of the thread id) to each line in the error stream. |
xxxxxx |
Any unkown parameter is interpretted as a context grammar entity. |
RESTful Interface
The NETS RESTful Interface allows the parser to be executed over an HTTP(S) protocol. The endpoint is http://europe-west2-nets3-webapp.cloudfunctions.net/process
and responds to a POST
with multi-part form data containing the input and the grammar.
A form which uses the endpoint is available at http://www.nets3.com/1.0/cloudplayground.xhtml.
An example using the cURL
utility is shown below.
> curl --location --request POST \
'http://europe-west2-nets3-webapp.cloudfunctions.net/process' \
--form 'output="default.out"' \
--form 'grammar=@"default.g"' \
--form 'input=@"default.in"' \
--form 'loglevel="4"' \
--form 'error="default.log"'
The curl command returns the output to the terminal. Any valid commandline argument can be used as part of the POST
. In addition the result_file
argument can be used to return any file generated during processing. For example result_file=default.log
returns the log file.
The /process POST
endpoint is synchronous with results returned as soon as processing is finished.
/process POST
returns the following HTTP message response codes.
Code | Description |
---|---|
200 |
Successful completion of the operation. |
JavaScript Interface
The NETS JavaScript Interface allows the parser to be executed from JavaScript code either using Node or a web browser. A Node example is shown below which requires the installation of the nets-parser npm module.
const Nets = require('nets-parser.js');
var args = {
input:'default_ouch.in',
output:'default.out',
grammar:'default.g',
error:'stderr',
loglevel:'3'
};
Nets().then(function(app) {
var parser=0;
parser=app.init(parser,args);
console.log(app.getContext(parser,'input'));
app.setContext(parser,'input','default.in')
console.log(app.getContext(parser,'input'));
app.start(parser);
process.exit();
});
An example Node project using NETS is available on Runkit.