Skip to content

Cicero v0.21.0
Compare
Choose a tag to compare
@jeromesimeon jeromesimeon released this 23 Jul 02:18
v0.21.0
6bf56c0

Transmute Release ⚗️

This is a major new release of Accord Project's Cicero templating system. This release includes an entirely new parsing and drafting engine built from the ground up with markdown in mind. It reduces the number of packages dependencies, and should result in better portability and performances.

The new implementation has several benefits:

  • It ensures consistency with the commonmark specification
  • It exposes a well-defined Document Object Model in JSON format for templates, called templatemark
  • It improves runtime performances and memory footprint

💥 There are a number of breaking changes which result from the integration of the template syntax into commonmark. See below for details.

🏗️ New parsing and drafting engine #547

Cicero parsing (from text to data) and drafting (from data to text) have been completely reimplemented. The new parsing/drafting engine can be found in the Accord Project markdown-transform project.

  • The parser for template grammars has been switched from Nearley to a proper plugin for the markdown-it library. This means Accord Project template grammars now behave as a proper markdown extension.
  • The template parser generation, underpinning cicero parse, has been switched from Nearley to parser combinators using the parsimmon library. This results in better performances, portability, and extensibility.

🎉 New Features

Template grammar

  • #389 Support for monetary amounts formats has been improved. You can now use an arbitrary number of digits after the decimal point (e.g., CCC 0,0.0000), no digit after the decimal point (e.g., CCC 0,0) and the number of monetary symbols handled has been expanded (e.g., when using a format such as K 0,0.00).
  • #17 #521 #549 A new optional template block {{#optional}} ... {{/optional}} allows templates to specify text for variables with an optional simple or complex type. As opposed to conditional template blocks, those can contain variables within the optional text. An example can be found in the template library.
  • A new {{this}} variable allows templates to handle variables with a list or optional simple type. An example can be found in the template library.

API

  • The draft call on Clause and contract instances now supports a format option for convenience. Supported formats include: html (HTML document), slate (the Slate Document Object Model supported by the rich text editor), ciceromark_parsed (the CiceroMark document object model with data / variables information).

💥 Breaking changes

Template grammar

Accord Project template grammar (usually the ./text/grammar.tem.md file in your templates) are now a proper extension of standard commonmark documents. While every effort has been made to reduce the impact on existing template, there are several breaking changes.

  • The commonmark specification distinguishes between blocks (e.g., paragraphs, lists) and inlines (e.g., text, links). A similar distinction now exists in template grammars, with: clause ({{#clause}}) and lists ({{#ulist}} and {{#olist}}) variables in templates corresponding to markdown blocks, and all other variables corresponding to markdown inlines.
  • Template variables corresponding to markdown blocks must be delimited using opening and closing tags starting with a newline, and ending with a new line. For instance:
{{#clause paymentClause}}Payment. As consideration in full for the rights granted herein, Licensee shall pay Licensor a one-time fee in the amount of {{amountText}} ({{amount}}) upon execution of this Agreement, payable as follows: {{paymentProcedure}}.{{/clause}}

Is no longer considered a clause, but will be parsed as a markdown paragraph. Instead, write:

{{#clause paymentClause}}
Payment. As consideration in full for the rights granted herein, Licensee shall pay Licensor a one-time fee in the amount of {{amountText}} ({{amount}}) upon execution of this Agreement, payable as follows: {{paymentProcedure}}.
{{/clause}}
  • Template variables corresponding to markdown inlines have to be written within a single markdown block (i.e., single heading, or single paragraph). For instance the following conditional which spans two markdown paragraphs is no longer supported:
{{#if forceMajeure}},except in the presence of

force majeure.{{/if}}
  • Code blocks can no longer contain variables. This is an inherent limitation in markdown parsers (and document model). i.e., the following code block containing a variable {{name}}
```js
function {{name}}(x) { return x; }
```

is no longer supported.

  • Template grammar blocks syntax now use the generic form: {{#kind name attributes}}More TemplateText{{/kind}}, where attributes are list of key="value" pairs. As a result the join block are now written: {{#join rates separator=“,”}}{{rate}}%{{/join}} rather than {{#join rates “,”}}{{rate}}%{{/join}}.

Contracts / Clauses

  • #4 Contract or clause text with repeated occurrences of the same variable will now fail parsing if the different occurrences differ. This allows for a stronger validation of the data in the text of your clause or contract.
  • #552 Parsing for relationships now returns the proper resource description so they can be distinguished from strings (i.e., "resource:org.accordproject.organization.Organization#Party%20A" rather than "Party A"). Drafting from data must use the same format.
  • Clauses within contract text now have to be delimited with the same {{#clause}}...{{/clause}} markup used in the corresponding contract template. See for instance the payment clause within the new copyright-license template.
  • Text in samples corresponding to Ergo formulas must now be written {{% ...some text... %}} rather than {{ ...some text...}}

API

  • The TemplateInstance.draft call is no longer an async
  • The parser manager class has been moved to https://github.com/accordproject/markdown-transform/blob/master/packages/markdown-template/lib/parsermanager.js and completely revised. Among some of the main changes:
    • The ParserManager.getGrammar call which used to return the Nearley grammar has been removed
    • The ParserManager.getTemplatizedGrammar, which returns the template grammar in textual form has been renamed to ParserManager.getTemplate
    • The ParserManager.buildGrammar call for parser construction has been renamed ParserManager.buildParser
    • The ParserManager.getParser now returns a Parsimmon parser combinator, rather than a Nearly parser
    • A new ParserManager.getTemplateMark call has been added, returning the template grammar Document Object Model
    • A new ParserManager.setTemplateMark allows to set the template grammar directly as TemplateMark (without the need for a grammar in textual form)

☎️ Cicero server (contribution by @martinhalford)

  • The interface to @accordproject/cicero-server has been cleaned up, and better documented.
  • The legacy CICERO_DATA environment variable and the corresponding (previously deprecated) /trigger/:template/:data endpoint has been removed.

🐛 Resolved Issues and Bug Fixes

This new release addresses a number of long standing issues and includes numerous bug fixes:

  • #4: Repeated bindings
  • #17 #549 #520: Optional parameters
  • #386: Remove use of Eval
  • #552: parsing for relationships
  • #553: Parser modularity
  • #554: Handling conditional at the end of paragraph
  • #555: Are conditional blocks markdown blocks!?
  • #531: Timezone when parsing dates
  • #404: Whitespace issues during template parsing
  • #386: Parser generation using JavaScript eval
  • #278: nujucks hack for parsing templates in the browser
Assets 2
Loading