Command Line Tools

Com­mand Line Tools

Whilst the Net­rium Con­tract Engin­eer is the most pro­duct­ive mech­an­ism to develop and sim­u­late con­tracts, there are times when a com­mand line tool may be more appro­pri­ate for a par­tic­u­lar devel­op­ment workflow.

Net­rium offers three com­mand line tools, all of which are cross plat­form and have been extens­ively tested on Linux, Microsoft Win­dows and OS X.

See also Using the Command Line Tools

Inter­me­di­ate Con­tract Format

All the com­mand line tools either pro­duce or con­sume the Inter­me­di­ate Con­tract Format. This XML based rep­res­ent­a­tion of a con­tract is the basis for execut­ing the con­tract and can be cross com­piled into other tech­no­lo­gies, such as C. Once in the Inter­me­di­ate Con­tract Format, the Con­tract is no longer in a Haskell form.

Com­piler

The Net­rium Com­piler (known as normalise) is used to com­pile the Haskell code and pro­duce the out­put Inter­me­di­ate Con­tract Format. It accepts the ori­ginal Haskell source file, plus an optional list of addi­tional mod­ules (for example, Net­rium includes a core lib­rary as well as an exten­ded Option lib­rary).

As with most com­pilers, the tool provides stdout and stderr access to com­piler errors, which can eas­ily be integ­rated into Con­tinu­ous Build environments.

Command Line Options

Usage: normalise [options] <input> [<output.xml>]

Option	Use
--obs-db=obsdb.xml	Specifies the Observable database (obsdb.xml)
--units-db=unitsdb.xml	Specifies the Units database (unitsdb.xml)
--import-dir=DIR	Specifies the folder to reference for modules referenced in the `import` statements
--fast	Outputs Intermediate Contract Language without any whitespace or pretty print formatting. Can reduce file size dramatically.
--version	Outputs the version information

Sim­u­lator

The Net­rium Sim­u­lator (known as simulate) is used to execute a con­tract. It accepts Inter­me­di­ate Con­tract Format, as well as time series data sets and a set of para­met­ers defin­ing how to execute the con­tract (at what time, until what time etc). The out­put is by default XML, and may include a resid­ual con­tract in Inter­me­di­ate Con­tract Format should the con­tract not have com­pleted execution due to being stopped due to missing observable data or being artificially stopped by the runtime options.

Command Line Options

Usage: simulate <contract.xml> <observations.xml> [<output.xml>]

Option	Use
--xml	Output in the standard XML based Intermediate Contract Format (default)
--text	Output in a readable text format
--trace	Outputs a trace of contract steps (useful for debugging).
--tests	Run internal tests to validate simulate behavior
--version	Outputs the version information

Visu­al­iser

The Visu­al­iser (known as visualise) is a tool used to cre­ate Visu­al­isa­tions of a con­tract that has a Inter­me­di­ate Con­tract Format rep­res­ent­a­tion. These visu­al­isa­tions are of two types: a syn­tax tree, which describes the contract’s struc­ture visu­ally as well as decision tree, which gives a view on how the Net­rium runtime will execute the con­tract. These visu­al­ised con­tracts can be saved in PNG, GraphViz Dot and SVG formats.

Note: Visualise requires GraphViz to be installed.

Command Line Options

Usage: visualise <contract.xml> [<output>]

Option	Use
--syntax-tree	Outputs the Syntax Tree
--decision-tree	Outputs the contract Decision Tree.
--start-time=TIME	Required for Decision Tree mode. This is the time at which the contract is acquired. For example: --start-time="2018-05-01 23:59:59"
--tree-depth=NUM	Limits the tree depth to a fixed amount. Default is 8.
--svg	Outputs a SVG file
--png	Outputs a PNG file. Depending on the operating system, the size of PNG may be constrained by the GraphViz runtime. SVG is recommended for all complex contracts.
--dot	Outputs a GraphViz dot file.
--version	Outputs the version information