Cicero Docs

Working with Node.js

Cicero Node.js API

You can work with Accord Project templates directly in JavaScript using Node.js.

Documentation for the API can be found in Cicero API.

Working with Templates

Import the Template class

To import the Cicero class for templates:

const Template = require('@accordproject/cicero-core').Template;

Copy

Load a Template

To create a Template instance in memory call the fromDirectory, fromArchive or fromUrl methods:

const template = await Template.fromDirectory('./test/data/latedeliveryandpenalty');

Copy

These methods are asynchronous and return a Promise, so you should use await to wait for the promise to be resolved.

Instantiate a Template

Once a Template has been loaded, you can create a Clause based on the Template. You can either instantiate the Clause using source DSL text (by calling parse), or you can set an instance of the template model as JSON data (by calling setData):

// load the DSL text for the template

const testLatePenaltyInput = fs.readFileSync(path.resolve(__dirname, 'data/', 'sample.txt'), 'utf8');

const clause = new Clause(template);

clause.parse(testLatePenaltyInput);

// get the JSON object created from the parse

const data = clause.getData();

Copy

OR - create a contract and set the data from a JSON object.

const clause = new Clause(template);

clause.setData( {$class: 'org.acme.MyTemplateModel', 'foo': 42 } );

Copy

Executing a Template Instance

Once you have instantiated a smart clause of contract instance, you can execute it.

Import the Engine class

To execute a Clause you first need to create an instance of the Engine class:

const Engine = require('@accordproject/cicero-engine').Engine;

Copy

Send a request to the contract

You can then call execute on it, passing in the clause or contract instance, and the request:

const request = {

'$class': 'org.accordproject.latedeliveryandpenalty.LateDeliveryAndPenaltyRequest',

'forceMajeure': false,

'agreedDelivery': '2017-10-07T16:38:01.412Z',

'goodsValue': 200,

'transactionId': '402c8f50-9e61-433e-a7c1-afe61c06ef00',

'timestamp': '2017-11-12T17:38:01.412Z'

};

const state = {};

state.$class = 'org.accordproject.cicero.contract.AccordContractState';

state.stateId = 'org.accordproject.cicero.contract.AccordContractState#1';

const result = await engine.execute(clause, request, state);

Copy

← Template Generator

Cicero API

Modules

cicero-engine

Clause Engine

cicero-core

Cicero Core - defines the core data types for Cicero.

Classes

Clause

A Clause is executable business logic, linked to a natural language (legally enforceable) template. A Clause must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the clause (an instance of the template model) by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

Contract

A Contract is executable business logic, linked to a natural language (legally enforceable) template. A Clause must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the clause (an instance of the template model) by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

DateTimeFormatParser

Parses a date/time format string

Metadata

Defines the metadata for a Template, including the name, version, README markdown.

ParserManager

Generates and manages a Nearley parser for a template.

Template

A template for a legal clause or contract. A Template has a template model, request/response transaction types, a template grammar (natural language for the template) as well as Ergo code for the business logic of the template.

TemplateInstance

A TemplateInstance is an instance of a Clause or Contract template. It is executable business logic, linked to a natural language (legally enforceable) template. A TemplateInstance must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the TemplateInstance by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

Functions

locationOfError(error) ⇒ object

Extract the file location from the parse error

cicero-engine

Clause Engine

cicero-engine

~Engine

new Engine()

.execute(clause, request, state, currentTime) ⇒ Promise

.invoke(clause, clauseName, params, state, currentTime) ⇒ Promise

.init(clause, currentTime) ⇒ Promise

.generateText(clause, [options], currentTime) ⇒ Promise

.getErgoEngine() ⇒ ErgoEngine

cicero-engine~Engine

Engine class. Stateless execution of clauses against a request object, returning a response to the caller.

Kind: inner class of cicero-engine

Access: public

~Engine

new Engine()

.execute(clause, request, state, currentTime) ⇒ Promise

.invoke(clause, clauseName, params, state, currentTime) ⇒ Promise

.init(clause, currentTime) ⇒ Promise

.generateText(clause, [options], currentTime) ⇒ Promise

.getErgoEngine() ⇒ ErgoEngine

new Engine()

Create the Engine.

engine.execute(clause, request, state, currentTime) ⇒ Promise

Send a request to a clause for execution

Kind: instance method of Engine

Returns: Promise - a promise that resolves to a result for the clause

Param Type Description

clause Clause the clause to execute

request object the request, a JS object that can be deserialized using the Composer serializer.

state object the contract state, a JS object that can be deserialized using the Composer serializer.

currentTime string the definition of 'now'

engine.invoke(clause, clauseName, params, state, currentTime) ⇒ Promise

Invoke a specific clause for execution

Kind: instance method of Engine

Returns: Promise - a promise that resolves to a result for the clause

Param Type Description

clause Clause the clause to execute

clauseName string the clause name

params object the clause parameters, a JS object whose fields that can be deserialized using the Composer serializer.

state object the contract state, a JS object that can be deserialized using the Composer serializer.

currentTime string the definition of 'now'

engine.init(clause, currentTime) ⇒ Promise

Initialize a clause

Kind: instance method of Engine

Returns: Promise - a promise that resolves to a result for the clause initialization

Param Type Description

clause Clause the clause to execute

currentTime string the definition of 'now'

engine.generateText(clause, [options], currentTime) ⇒ Promise

Generate Text for a clause

Kind: instance method of Engine

Returns: Promise - a promise that resolves to a result for the clause initialization

Param Type Description

clause Clause the clause to execute

[options] * text generation options. options.wrapVariables encloses variables and editable sections in '<variable ...' and '/>'

currentTime string the definition of 'now'

engine.getErgoEngine() ⇒ ErgoEngine

Provides access to the underlying Ergo engine.

Kind: instance method of Engine

Returns: ErgoEngine - the Ergo Engine for this Engine

cicero-core

Cicero Core - defines the core data types for Cicero.

Clause

Kind: global class

Access: public

Contract

Kind: global class

Access: public

DateTimeFormatParser

Parses a date/time format string

Kind: global class

Access: public

DateTimeFormatParser

.parseDateTimeFormatField(field) ⇒ string

.buildDateTimeFormatRule(formatString) ⇒ Object

DateTimeFormatParser.parseDateTimeFormatField(field) ⇒ string

Given a format field (like HH or D) this method returns a logical name for the field. Note the logical names have been picked to align with the moment constructor that takes an object.

Kind: static method of DateTimeFormatParser

Returns: string - the field designator

Param Type Description

field string the input format field

DateTimeFormatParser.buildDateTimeFormatRule(formatString) ⇒ Object

Converts a format string to a Nearley action

Kind: static method of DateTimeFormatParser

Returns: Object - the tokens and action and name to use for the Nearley rule

Param Type Description

formatString string the input format string

Metadata

Defines the metadata for a Template, including the name, version, README markdown.

Kind: global class

Access: public

Metadata

new Metadata(packageJson, readme, samples, request)

.getTemplateType() ⇒ number

.getRuntime() ⇒ string

.getErgoVersion() ⇒ string

.getCiceroVersion() ⇒ string

.satisfiesCiceroVersion(version) ⇒ string

.getSamples() ⇒ object

.getRequest() ⇒ object

.getSample(locale) ⇒ string

.getREADME() ⇒ String

.getPackageJson() ⇒ object

.getName() ⇒ string

.getDisplayName() ⇒ string

.getKeywords() ⇒ Array

.getDescription() ⇒ string

.getVersion() ⇒ string

.getIdentifier() ⇒ string

.createTargetMetadata(runtimeName) ⇒ object

new Metadata(packageJson, readme, samples, request)

Create the Metadata.

Note: Only to be called by framework code. Applications should retrieve instances from [Template](#Template)

Param Type Description

packageJson object the JS object for package.json (required)

readme String the README.md for the template (may be null)

samples object the sample markdown for the template in different locales,

request object the JS object for the sample request represented as an object whose keys are the locales and whose values are the sample markdown. For example: { default: 'default sample markdown', en: 'sample text in english', fr: 'exemple de texte français' } Locale keys (with the exception of default) conform to the IETF Language Tag specification (BCP 47). THe default key represents sample template text in a non-specified language, stored in a file called sample.md.

metadata.getTemplateType() ⇒ number

Returns either a 0 (for a contract template), or 1 (for a clause template)

Kind: instance method of Metadata

Returns: number - the template type

metadata.getRuntime() ⇒ string

Returns the name of the runtime target for this template, or null if this template has not been compiled for a specific runtime.

Kind: instance method of Metadata

Returns: string - the name of the runtime

metadata.getErgoVersion() ⇒ string

Returns the Ergo version that the Ergo code in this template is compatible with. This is null for templates that do not contain source Ergo code.

Kind: instance method of Metadata

Returns: string - the version of Ergo

metadata.getCiceroVersion() ⇒ string

Returns the version of Cicero that this template is compatible with. i.e. which version of the runtime was this template built for? The version string conforms to the semver definition

Kind: instance method of Metadata

Returns: string - the semantic version

metadata.satisfiesCiceroVersion(version) ⇒ string

Only returns true if the current cicero version satisfies the target version of this template

Kind: instance method of Metadata

Returns: string - the semantic version

Param Type Description

version string the cicero version to check against

metadata.getSamples() ⇒ object

Returns the samples for this template.

Kind: instance method of Metadata

Returns: object - the sample files for the template

metadata.getRequest() ⇒ object

Returns the sample request for this template.

Kind: instance method of Metadata

Returns: object - the sample request for the template

metadata.getSample(locale) ⇒ string

Returns the sample for this template in the given locale. This may be null. If no locale is specified returns the default sample if it has been specified.

Kind: instance method of Metadata

Returns: string - the sample file for the template in the given locale or null

Param Type Default Description

locale string null the IETF language code for the language.

metadata.getREADME() ⇒ String

Returns the README.md for this template. This may be null if the template does not have a README.md

Kind: instance method of Metadata

Returns: String - the README.md file for the template or null

metadata.getPackageJson() ⇒ object

Returns the package.json for this template.

Kind: instance method of Metadata

Returns: object - the Javascript object for package.json

metadata.getName() ⇒ string

Returns the name for this template.

Kind: instance method of Metadata

Returns: string - the name of the template

metadata.getDisplayName() ⇒ string

Returns the display name for this template.

Kind: instance method of Metadata

Returns: string - the display name of the template

metadata.getKeywords() ⇒ Array

Returns the name for this template.

Kind: instance method of Metadata

Returns: Array - the name of the template

metadata.getDescription() ⇒ string

Returns the description for this template.

Kind: instance method of Metadata

Returns: string - the description of the template

metadata.getVersion() ⇒ string

Returns the version for this template.

Kind: instance method of Metadata

Returns: string - the description of the template

metadata.getIdentifier() ⇒ string

Returns the identifier for this template, formed from name@version.

Kind: instance method of Metadata

Returns: string - the identifier of the template

metadata.createTargetMetadata(runtimeName) ⇒ object

Return new Metadata for a target runtime

Kind: instance method of Metadata

Returns: object - the new Metadata

Param Type Description

runtimeName string the target runtime name

ParserManager

Generates and manages a Nearley parser for a template.

Kind: global class

ParserManager

new ParserManager(template)

instance

.getParser() ⇒ object

.getTemplateAst() ⇒ object

.setGrammar(grammar)

.buildGrammar(templatizedGrammar)

.buildGrammarRules(ast, templateModel, prefix, parts)

.handleBinding(templateModel, parts, inputRule, element)

.cleanChunk(input) ⇒ string

.findFirstBinding(propertyName, elements) ⇒ int

.getGrammar() ⇒ String

.getTemplatizedGrammar() ⇒ String

.roundtripMarkdown(text) ⇒ string

static

.getProperty(templateModel, element) ⇒ *

._throwTemplateExceptionForElement(message, element)

.compileGrammar(sourceCode) ⇒ object

new ParserManager(template)

Create the ParserManager.

Param Type Description

template object the template instance

parserManager.getParser() ⇒ object

Gets a parser object for this template

Kind: instance method of ParserManager

Returns: object - the parser for this template

parserManager.getTemplateAst() ⇒ object

Gets the AST for the template

Kind: instance method of ParserManager

Returns: object - the AST for the template

parserManager.setGrammar(grammar)

Set the grammar for the template

Kind: instance method of ParserManager

Param Type Description

grammar String the grammar for the template

parserManager.buildGrammar(templatizedGrammar)

Build a grammar from a template

Kind: instance method of ParserManager

Param Type Description

templatizedGrammar String the annotated template using the markdown parser

parserManager.buildGrammarRules(ast, templateModel, prefix, parts)

Build grammar rules from a template

Kind: instance method of ParserManager

Param Type Description

ast object the AST from which to build the grammar

templateModel ClassDeclaration the type of the parent class for this AST

prefix String A unique prefix for the grammar rules

parts Object Result object to acculumate rules and required sub-grammars

parserManager.handleBinding(templateModel, parts, inputRule, element)

Utility method to generate a grammar rule for a variable binding

Kind: instance method of ParserManager

Param Type Description

templateModel ClassDeclaration the current template model

parts * the parts, where the rule will be added

inputRule * the rule we are processing in the AST

element * the current element in the AST

parserManager.cleanChunk(input) ⇒ string

Cleans a chunk of text to make it safe to include as a grammar rule. We need to remove linefeeds and escape any '"' characters.

Kind: instance method of ParserManager

Returns: string - cleaned text

Param Type Description

input string the input text from the template

parserManager.findFirstBinding(propertyName, elements) ⇒ int

Finds the first binding for the given property

Kind: instance method of ParserManager

Returns: int - the index of the element or -1

Param Type Description

propertyName string the name of the property

elements Array.<object> the result of parsing the template_txt.

parserManager.getGrammar() ⇒ String

Get the (compiled) grammar for the template

Kind: instance method of ParserManager

Returns: String - - the grammar for the template

parserManager.getTemplatizedGrammar() ⇒ String

Returns the templatized grammar

Kind: instance method of ParserManager

Returns: String - the contents of the templatized grammar

parserManager.roundtripMarkdown(text) ⇒ string

Round-trip markdown

Kind: instance method of ParserManager

Returns: string - the result of parsing and printing back the text

Param Type Description

text string the markdown text

ParserManager.getProperty(templateModel, element) ⇒ *

Throws an error if a template variable doesn't exist on the model.

Kind: static method of ParserManager

Returns: * - the property

Param Type Description

templateModel * the model for the template

element * the current element in the AST

ParserManager._throwTemplateExceptionForElement(message, element)

Throw a template exception for the element

Kind: static method of ParserManager

Throws:

TemplateException

Param Type Description

message string the error message

element object the AST

ParserManager.compileGrammar(sourceCode) ⇒ object

Compiles a Nearley grammar to its AST

Kind: static method of ParserManager

Returns: object - the AST for the grammar

Param Type Description

sourceCode string the source text for the grammar

Template

Kind: global abstract class

Access: public

Template

new Template(packageJson, readme, samples, request, options)

instance

.validate()

.getTemplateModel() ⇒ ClassDeclaration

.getIdentifier() ⇒ String

.getMetadata() ⇒ Metadata

.getName() ⇒ String

.getDisplayName() ⇒ string

.getVersion() ⇒ String

.getDescription() ⇒ String

.getHash() ⇒ string

.toArchive([language], [options]) ⇒ Promise.<Buffer>

.getParserManager() ⇒ ParserManager

.getLogicManager() ⇒ LogicManager

.getIntrospector() ⇒ Introspector

.getFactory() ⇒ Factory

.getSerializer() ⇒ Serializer

.getRequestTypes() ⇒ Array

.getResponseTypes() ⇒ Array

.getEmitTypes() ⇒ Array

.getStateTypes() ⇒ Array

.hasLogic() ⇒ boolean

static

.fromDirectory(path, [options]) ⇒ Promise.<Template>

.fromArchive(buffer, [options]) ⇒ Promise.<Template>

.fromUrl(url, [options]) ⇒ Promise

.instanceOf(classDeclaration, fqt) ⇒ boolean

new Template(packageJson, readme, samples, request, options)

Create the Template. Note: Only to be called by framework code. Applications should retrieve instances from fromArchive or fromDirectory.

Param Type Description

packageJson object the JS object for package.json

readme String the readme in markdown for the template (optional)

samples object the sample text for the template in different locales

request object the JS object for the sample request

options Object e.g., { warnings: true }

template.validate()

Verifies that the template is well formed. Throws an exception with the details of any validation errors.

Kind: instance method of Template

template.getTemplateModel() ⇒ ClassDeclaration

Returns the template model for the template

Kind: instance method of Template

Returns: ClassDeclaration - the template model for the template

Throws:

Error if no template model is found, or multiple template models are found

template.getIdentifier() ⇒ String

Returns the identifier for this template

Kind: instance method of Template

Returns: String - the identifier of this template

template.getMetadata() ⇒ Metadata

Returns the metadata for this template

Kind: instance method of Template

Returns: Metadata - the metadata for this template

template.getName() ⇒ String

Returns the name for this template

Kind: instance method of Template

Returns: String - the name of this template

template.getDisplayName() ⇒ string

Returns the display name for this template.

Kind: instance method of Template

Returns: string - the display name of the template

template.getVersion() ⇒ String

Returns the version for this template

Kind: instance method of Template

Returns: String - the version of this template. Use semver module to parse.

template.getDescription() ⇒ String

Returns the description for this template

Kind: instance method of Template

Returns: String - the description of this template

template.getHash() ⇒ string

Gets a content based SHA-256 hash for this template. Hash is based on the metadata for the template plus the contents of all the models and all the script files.

Kind: instance method of Template

Returns: string - the SHA-256 hash in hex format

template.toArchive([language], [options]) ⇒ Promise.<Buffer>

Persists this template to a Cicero Template Archive (cta) file.

Kind: instance method of Template

Returns: Promise.<Buffer> - the zlib buffer

Param Type Description

[language] string target language for the archive (should be 'ergo')

[options] Object JSZip options

template.getParserManager() ⇒ ParserManager

Provides access to the parser manager for this template. The parser manager can convert template data to and from natural language text.

Kind: instance method of Template

Returns: ParserManager - the ParserManager for this template

template.getLogicManager() ⇒ LogicManager

Provides access to the template logic for this template. The template logic encapsulate the code necessary to execute the clause or contract.

Kind: instance method of Template

Returns: LogicManager - the LogicManager for this template

template.getIntrospector() ⇒ Introspector

Provides access to the Introspector for this template. The Introspector is used to reflect on the types defined within this template.

Kind: instance method of Template

Returns: Introspector - the Introspector for this template

template.getFactory() ⇒ Factory

Provides access to the Factory for this template. The Factory is used to create the types defined in this template.

Kind: instance method of Template

Returns: Factory - the Factory for this template

template.getSerializer() ⇒ Serializer

Provides access to the Serializer for this template. The Serializer is used to serialize instances of the types defined within this template.

Kind: instance method of Template

Returns: Serializer - the Serializer for this template

template.getRequestTypes() ⇒ Array

Provides a list of the input types that are accepted by this Template. Types use the fully-qualified form.

Kind: instance method of Template

Returns: Array - a list of the request types

template.getResponseTypes() ⇒ Array

Provides a list of the response types that are returned by this Template. Types use the fully-qualified form.

Kind: instance method of Template

Returns: Array - a list of the response types

template.getEmitTypes() ⇒ Array

Provides a list of the emit types that are emitted by this Template. Types use the fully-qualified form.

Kind: instance method of Template

Returns: Array - a list of the emit types

template.getStateTypes() ⇒ Array

Provides a list of the state types that are expected by this Template. Types use the fully-qualified form.

Kind: instance method of Template

Returns: Array - a list of the state types

template.hasLogic() ⇒ boolean

Returns true if the template has logic, i.e. has more than one script file.

Kind: instance method of Template

Returns: boolean - true if the template has logic

Template.fromDirectory(path, [options]) ⇒ Promise.<Template>

Builds a Template from the contents of a directory. The directory must include a package.json in the root (used to specify the name, version and description of the template).

Kind: static method of Template

Returns: Promise.<Template> - a Promise to the instantiated template

Param Type Default Description

path String to a local directory

[options] Object an optional set of options to configure the instance.

Template.fromArchive(buffer, [options]) ⇒ Promise.<Template>

Create a template from an archive.

Kind: static method of Template

Returns: Promise.<Template> - a Promise to the template

Param Type Default Description

buffer Buffer the buffer to a Cicero Template Archive (cta) file

[options] Object an optional set of options to configure the instance.

Template.fromUrl(url, [options]) ⇒ Promise

Create a template from an URL.

Kind: static method of Template

Returns: Promise - a Promise to the template

Param Type Default Description

url String the URL to a Cicero Template Archive (cta) file

[options] Object an optional set of options to configure the instance.

Template.instanceOf(classDeclaration, fqt) ⇒ boolean

Check to see if a ClassDeclaration is an instance of the specified fully qualified type name.

Kind: static method of Template

Returns: boolean - True if classDeclaration an instance of the specified fully qualified type name, false otherwise.

Internal:

Param Type Description

classDeclaration ClassDeclaration The class to test

fqt String The fully qualified type name.

TemplateInstance

Kind: global abstract class

Access: public

TemplateInstance

new TemplateInstance(template)

instance

.setData(data)

.getData() ⇒ object

.getEngine() ⇒ object

.getDataAsConcertoObject() ⇒ object

.parse(input, [currentTime], [fileName])

.generateText([options], currentTime) ⇒ string

.getIdentifier() ⇒ String

.getTemplate() ⇒ Template

.getLogicManager() ⇒ LogicManager

.toJSON() ⇒ object

static

.convertDateTimes(obj, utcOffset) ⇒ *

new TemplateInstance(template)

Create the Clause and link it to a Template.

Param Type Description

template Template the template for the clause

templateInstance.setData(data)

Set the data for the clause

Kind: instance method of TemplateInstance

Param Type Description

data object the data for the clause, must be an instance of the template model for the clause's template. This should be a plain JS object and will be deserialized and validated into the Concerto object before assignment.

templateInstance.getData() ⇒ object

Get the data for the clause. This is a plain JS object. To retrieve the Concerto object call getConcertoData().

Kind: instance method of TemplateInstance

Returns: object - - the data for the clause, or null if it has not been set

templateInstance.getEngine() ⇒ object

Get the current Ergo engine

Kind: instance method of TemplateInstance

Returns: object - - the data for the clause, or null if it has not been set

templateInstance.getDataAsConcertoObject() ⇒ object

Get the data for the clause. This is a Concerto object. To retrieve the plain JS object suitable for serialization call toJSON() and retrieve the data property.

Kind: instance method of TemplateInstance

Returns: object - - the data for the clause, or null if it has not been set

templateInstance.parse(input, [currentTime], [fileName])

Set the data for the clause by parsing natural language text.

Kind: instance method of TemplateInstance

Param Type Description

input string the text for the clause

[currentTime] string the definition of 'now' (optional)

[fileName] string the fileName for the text (optional)

templateInstance.generateText([options], currentTime) ⇒ string

Generates the natural language text for a contract or clause clause; combining the text from the template and the instance data.

Kind: instance method of TemplateInstance

Returns: string - the natural language text for the contract or clause; created by combining the structure of the template with the JSON data for the clause.

Param Type Description

[options] * text generation options. options.wrapVariables encloses variables and editable sections in '<variable ...' and '/>'

currentTime string the definition of 'now' (optional)

templateInstance.getIdentifier() ⇒ String

Returns the identifier for this clause. The identifier is the identifier of the template plus '-' plus a hash of the data for the clause (if set).

Kind: instance method of TemplateInstance

Returns: String - the identifier of this clause

templateInstance.getTemplate() ⇒ Template

Returns the template for this clause

Kind: instance method of TemplateInstance

Returns: Template - the template for this clause

templateInstance.getLogicManager() ⇒ LogicManager

Returns the template logic for this clause

Kind: instance method of TemplateInstance

Returns: LogicManager - the template for this clause

templateInstance.toJSON() ⇒ object

Returns a JSON representation of the clause

Kind: instance method of TemplateInstance

Returns: object - the JS object for serialization

TemplateInstance.convertDateTimes(obj, utcOffset) ⇒ *

Recursive function that converts all instances of ParsedDateTime to a Moment.

Kind: static method of TemplateInstance

Returns: * - the converted object

Param Type Description

obj * the input object

utcOffset number the default utcOffset

locationOfError(error) ⇒ object

Extract the file location from the parse error

Kind: global function

Returns: object - - the file location information

Param Type Description

error object the parse error

← Markdown Transform CLI