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.
- Metadata
Defines the metadata for a Template, including the name, version, README markdown.
- 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.
- CompositeArchiveLoader
Manages a set of archive loaders, delegating to the first archive loader that accepts a URL.
Functions
- isPNG(buffer) ⇒
Boolean
Checks whether the file is PNG
- getMimeType(buffer) ⇒
Object
Returns the mime-type of the file
cicero-engine
Clause Engine
cicero-engine.Engine
Engine class. Stateless execution of clauses against a request object, returning a response to the caller.
Kind: static class of cicero-engine
Access: public
new Engine()
Create the Engine.
Promise
engine.trigger(clause, request, state, [currentTime], [utcOffset]) ⇒ 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 |
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', defaults to current time |
[utcOffset] | number | UTC Offset for this execution, defaults to local offset |
Promise
engine.invoke(clause, clauseName, params, state, [currentTime], [utcOffset]) ⇒ 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 |
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', defaults to current time |
[utcOffset] | number | UTC Offset for this execution, defaults to local offset |
Promise
engine.init(clause, [currentTime], [utcOffset], params) ⇒ 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 |
[currentTime] | string | the definition of 'now', defaults to current time |
[utcOffset] | number | UTC Offset for this execution, defaults to local offset |
params | object | the clause parameters, a JS object whose fields that can be deserialized using the Composer serializer. |
ErgoEngine
engine.getErgoEngine() ⇒ 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
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.
Kind: global class
Access: public
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.
Kind: global class
Access: public
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, logo)
- instance
- .getTemplateType() ⇒
number
- .getLogo() ⇒
Buffer
- .getAuthor() ⇒
*
- .getRuntime() ⇒
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
- .toJSON() ⇒
object
- .getTemplateType() ⇒
- static
new Metadata(packageJson, readme, samples, request, logo)
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 |
logo | Buffer | the bytes data for the image 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 . |
number
metadata.getTemplateType() ⇒ Returns either a 0 (for a contract template), or 1 (for a clause template)
Kind: instance method of Metadata
Returns: number
- the template type
Buffer
metadata.getLogo() ⇒ Returns the logo at the root of the template
Kind: instance method of Metadata
Returns: Buffer
- the bytes data of logo
*
metadata.getAuthor() ⇒ Returns the author for this template.
Kind: instance method of Metadata
Returns: *
- the author information
string
metadata.getRuntime() ⇒ 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
string
metadata.getCiceroVersion() ⇒ 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
string
metadata.satisfiesCiceroVersion(version) ⇒ 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 |
object
metadata.getSamples() ⇒ Returns the samples for this template.
Kind: instance method of Metadata
Returns: object
- the sample files for the template
object
metadata.getRequest() ⇒ Returns the sample request for this template.
Kind: instance method of Metadata
Returns: object
- the sample request for the template
string
metadata.getSample(locale) ⇒ 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. |
String
metadata.getREADME() ⇒ 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
object
metadata.getPackageJson() ⇒ Returns the package.json for this template.
Kind: instance method of Metadata
Returns: object
- the Javascript object for package.json
string
metadata.getName() ⇒ Returns the name for this template.
Kind: instance method of Metadata
Returns: string
- the name of the template
string
metadata.getDisplayName() ⇒ Returns the display name for this template.
Kind: instance method of Metadata
Returns: string
- the display name of the template
Array
metadata.getKeywords() ⇒ Returns the keywords for this template.
Kind: instance method of Metadata
Returns: Array
- the keywords of the template
string
metadata.getDescription() ⇒ Returns the description for this template.
Kind: instance method of Metadata
Returns: string
- the description of the template
string
metadata.getVersion() ⇒ Returns the version for this template.
Kind: instance method of Metadata
Returns: string
- the description of the template
string
metadata.getIdentifier() ⇒ Returns the identifier for this template, formed from name@version.
Kind: instance method of Metadata
Returns: string
- the identifier of the template
object
metadata.createTargetMetadata(runtimeName) ⇒ 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 |
object
metadata.toJSON() ⇒ Return the whole metadata content, for hashing
Kind: instance method of Metadata
Returns: object
- the content of the metadata object
Metadata.checkImage(buffer)
Check the buffer is a png file with the right size
Kind: static method of Metadata
Param | Type | Description |
---|---|---|
buffer | Buffer | the buffer object |
Metadata.checkImageDimensions(buffer, mimeType)
Checks if dimensions for the image are correct.
Kind: static method of Metadata
Param | Type | Description |
---|---|---|
buffer | Buffer | the buffer object |
mimeType | string | the mime type of the object |
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.
Kind: global abstract class
Access: public
- Template
- new Template(packageJson, readme, samples, request, logo, options)
- instance
- .validate()
- .getTemplateModel() ⇒
ClassDeclaration
- .getIdentifier() ⇒
String
- .getMetadata() ⇒
Metadata
- .getName() ⇒
String
- .getDisplayName() ⇒
string
- .getVersion() ⇒
String
- .getDescription() ⇒
String
- .getHash() ⇒
string
- .toArchive([language], [options], logo) ⇒
Promise.<Buffer>
- .getParserManager() ⇒
ParserManager
- .getLogicManager() ⇒
LogicManager
- .getIntrospector() ⇒
Introspector
- .getFactory() ⇒
Factory
- .getSerializer() ⇒
Serializer
- .getRequestTypes() ⇒
Array
- .getResponseTypes() ⇒
Array
- .getEmitTypes() ⇒
Array
- .getStateTypes() ⇒
Array
- .hasLogic() ⇒
boolean
- static
new Template(packageJson, readme, samples, request, logo, 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 |
logo | Buffer | the bytes data of logo |
options | Object | e.g., { warnings: true } |
template.validate()
Verifies that the template is well formed. Compiles the Ergo logic. Throws an exception with the details of any validation errors.
Kind: instance method of Template
ClassDeclaration
template.getTemplateModel() ⇒ 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
String
template.getIdentifier() ⇒ Returns the identifier for this template
Kind: instance method of Template
Returns: String
- the identifier of this template
Metadata
template.getMetadata() ⇒ Returns the metadata for this template
Kind: instance method of Template
Returns: Metadata
- the metadata for this template
String
template.getName() ⇒ Returns the name for this template
Kind: instance method of Template
Returns: String
- the name of this template
string
template.getDisplayName() ⇒ Returns the display name for this template.
Kind: instance method of Template
Returns: string
- the display name of the template
String
template.getVersion() ⇒ Returns the version for this template
Kind: instance method of Template
Returns: String
- the version of this template. Use semver module
to parse.
String
template.getDescription() ⇒ Returns the description for this template
Kind: instance method of Template
Returns: String
- the description of this template
string
template.getHash() ⇒ 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
Promise.<Buffer>
template.toArchive([language], [options], logo) ⇒ 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 |
logo | Buffer | Bytes data of the PNG file |
ParserManager
template.getParserManager() ⇒ 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
LogicManager
template.getLogicManager() ⇒ 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
Introspector
template.getIntrospector() ⇒ 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
Factory
template.getFactory() ⇒ 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
Serializer
template.getSerializer() ⇒ 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
Array
template.getRequestTypes() ⇒ 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
Array
template.getResponseTypes() ⇒ 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
Array
template.getEmitTypes() ⇒ 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
Array
template.getStateTypes() ⇒ 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
boolean
template.hasLogic() ⇒ 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
Promise.<Template>
Template.fromDirectory(path, [options]) ⇒ 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. |
Promise.<Template>
Template.fromArchive(buffer, [options]) ⇒ 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. |
Promise
Template.fromUrl(url, [options]) ⇒ 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. |
boolean
Template.instanceOf(classDeclaration, fqt) ⇒ 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
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.
Kind: global abstract class
Access: public
- TemplateInstance
- new TemplateInstance(template)
- instance
- .setData(data)
- .getData() ⇒
object
- .getEngine() ⇒
object
- .getDataAsConcertoObject() ⇒
object
- .parse(input, [currentTime], [utcOffset], [fileName])
- .draft([options], [currentTime], [utcOffset]) ⇒
string
- .formatCiceroMark(ciceroMarkParsed, options, format) ⇒
string
- .getIdentifier() ⇒
String
- .getTemplate() ⇒
Template
- .getLogicManager() ⇒
LogicManager
- .toJSON() ⇒
object
- static
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. |
object
templateInstance.getData() ⇒ 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
object
templateInstance.getEngine() ⇒ 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
object
templateInstance.getDataAsConcertoObject() ⇒ 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], [utcOffset], [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', defaults to current time |
[utcOffset] | number | UTC Offset for this execution, defaults to local offset |
[fileName] | string | the fileName for the text (optional) |
string
templateInstance.draft([options], [currentTime], [utcOffset]) ⇒ 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. |
[currentTime] | string | the definition of 'now', defaults to current time |
[utcOffset] | number | UTC Offset for this execution, defaults to local offset |
string
templateInstance.formatCiceroMark(ciceroMarkParsed, options, format) ⇒ Format CiceroMark
Kind: instance method of TemplateInstance
Returns: string
- the result of parsing and printing back the text
Param | Type | Description |
---|---|---|
ciceroMarkParsed | object | the parsed CiceroMark DOM |
options | object | parameters to the formatting |
format | string | to the text generation |
String
templateInstance.getIdentifier() ⇒ 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
Template
templateInstance.getTemplate() ⇒ Returns the template for this clause
Kind: instance method of TemplateInstance
Returns: Template
- the template for this clause
LogicManager
templateInstance.getLogicManager() ⇒ Returns the template logic for this clause
Kind: instance method of TemplateInstance
Returns: LogicManager
- the template for this clause
object
templateInstance.toJSON() ⇒ Returns a JSON representation of the clause
Kind: instance method of TemplateInstance
Returns: object
- the JS object for serialization
*
TemplateInstance.ciceroFormulaEval(logicManager, clauseId, ergoEngine, name) ⇒ Constructs a function for formula evaluation based for this template instance
Kind: static method of TemplateInstance
Returns: *
- A function from formula code + input data to result
Param | Type | Description |
---|---|---|
logicManager | * | the logic manager |
clauseId | string | this instance identifier |
ergoEngine | * | the evaluation engine |
name | string | the name of the formula |
TemplateInstance.rebuildParser(parserManager, logicManager, ergoEngine, templateName, grammar)
Utility to rebuild a parser when the grammar changes
Kind: static method of TemplateInstance
Param | Type | Description |
---|---|---|
parserManager | * | the parser manager |
logicManager | * | the logic manager |
ergoEngine | * | the evaluation engine |
templateName | string | this template name |
grammar | string | the new grammar |
CompositeArchiveLoader
Manages a set of archive loaders, delegating to the first archive loader that accepts a URL.
Kind: global class
new CompositeArchiveLoader()
Create the CompositeArchiveLoader. Used to delegate to a set of ArchiveLoaders.
compositeArchiveLoader.addArchiveLoader(archiveLoader)
Adds a ArchiveLoader implemenetation to the ArchiveLoader
Kind: instance method of CompositeArchiveLoader
Param | Type | Description |
---|---|---|
archiveLoader | ArchiveLoader | The archive to add to the CompositeArchiveLoader |
compositeArchiveLoader.clearArchiveLoaders()
Remove all registered ArchiveLoaders
Kind: instance method of CompositeArchiveLoader
boolean
compositeArchiveLoader.accepts(url) ⇒ Returns true if this ArchiveLoader can process the URL
Kind: instance abstract method of CompositeArchiveLoader
Returns: boolean
- true if this ArchiveLoader accepts the URL
Param | Type | Description |
---|---|---|
url | string | the URL |
Promise
compositeArchiveLoader.load(url, options) ⇒ Load a Archive from a URL and return it
Kind: instance method of CompositeArchiveLoader
Returns: Promise
- a promise to the Archive
Param | Type | Description |
---|---|---|
url | string | the url to get |
options | object | additional options |
Boolean
isPNG(buffer) ⇒ Checks whether the file is PNG
Kind: global function
Returns: Boolean
- whether the file in PNG
Param | Type | Description |
---|---|---|
buffer | Buffer | buffer of the file |
Object
getMimeType(buffer) ⇒ Returns the mime-type of the file
Kind: global function
Returns: Object
- the mime-type of the file
Param | Type | Description |
---|---|---|
buffer | Buffer | buffer of the file |