From 2a6250724b904391555b73cff4aef481b905d866 Mon Sep 17 00:00:00 2001 From: Katie Date: Thu, 31 Oct 2019 13:51:42 +0000 Subject: [PATCH 1/2] Updated cicero-cli and ergo-cli for 0.20 release Signed-off-by: Katie --- docs/cicero-cli.md | 228 ++++++++++++++++++++++------- docs/concerto-cli.md | 2 +- docs/ergo-cli.md | 333 +++++++++++++++++++++++++++++++++--------- docs/markup-cicero.md | 41 +++++- website/i18n/en.json | 2 +- website/sidebars.json | 2 +- 6 files changed, 479 insertions(+), 129 deletions(-) diff --git a/docs/cicero-cli.md b/docs/cicero-cli.md index 859052f8..6d170bb0 100644 --- a/docs/cicero-cli.md +++ b/docs/cicero-cli.md @@ -5,73 +5,203 @@ title: Cicero CLI Install the `@accordproject/cicero-cli` npm package to access the Cicero command line interface (CLI). After installation you can use the `cicero` command and its sub-commands as described below. +To install the Cicero CLI: +``` +npm install -g @accordproject/cicero-cli@0.20.0 +``` + +## Usage + +```md +Commands: + cicero parse parse a contract text + cicero draft create contract text from data + cicero normalize normalize markdown (parse & redraft) + cicero trigger send a request to the contract + cicero invoke invoke a clause of the contract + cicero initialize initialize a clause + cicero archive create a template archive + cicero compile generate code for a target platform + cicero get save local copies of external dependencies + +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + +``` + ## cicero parse -Loads a template from a directory on disk and then parses input clause (or contract) text using the template. -If successful the template model is printed to console. If there are syntax errors in the DSL -text the line and column and error information are printed. +`cicero parse` loads a template from a directory on disk and then parses input clause (or contract) text using the template. If successful, the template model is printed to console. If there are syntax errors, the line and column and error information are printed. + +```md +cicero parse + +parse a contract text + +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --sample path to the contract text [string] + --output path to the output file [string] + --currentTime set current time [string] [default: null] + --warnings print warnings [boolean] [default: false] +``` + +## cicero draft + +`cicero draft` creates contract text from data. + +```md +create contract text from data + +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --data path to the contract data [string] + --output path to the output file [string] + --currentTime set current time [string] [default: null] + --wrapVariables wrap variables as XML tags [boolean] [default: false] + --warnings print warnings [boolean] [default: false] +``` + +## cicero normalize + +`cicero normalize` normalizes markdown text by parsing and redrafting the text. -```bash - cicero parse +```md +normalize markdown (parse & redraft) - Options: - --help Show help [boolean] - --version Show version number [boolean] - --template path to the directory with the template [string] - --sample path to the clause text [string] - --out path to the output file [string] - --verbose, -v [default: false] +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --sample path to the contract text [string] + --overwrite overwrite the contract text [boolean] [default: false] + --output path to the output file [string] + --currentTime set current time [string] [default: null] + --warnings print warnings [boolean] [default: false] + --wrapVariables wrap variables as XML tags [boolean] [default: false] ``` -## cicero execute +## cicero trigger + +`cicero trigger` sends a request to the contract. -Loads a template from a directory on disk and then attempts to create a clause (or contract)from a given input -text. If the clause (or contract) is successfully created, it is then executed by the engine, passing in JSON data. If successful the -engine response is printed to the console. +```md +send a request to the contract -```bash - cicero execute +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --sample path to the contract text [string] + --request path to the JSON request [array] + --state path to the JSON state [string] + --currentTime set current time [string] [default: null] + --warnings print warnings [boolean] [default: false] - Options: - --help Show help [boolean] - --version Show version number [boolean] - --template path to the directory with the template [string] - --sample path to the clause text [string] - --request path to the JSON request [array] - --state path to the JSON state [string] - --verbose, -v [default: false] ``` +## cicero invoke + +`cicero invoke` invokes a specific clause (`--clauseName`) of the contract. + +```md +invoke a clause of the contract + +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --sample path to the contract text [string] + --clauseName the name of the clause to invoke [string] + --params path to the parameters [string] + --state path to the JSON state [string] + --currentTime set current time [string] [default: null] + --warnings print warnings [boolean] [default: false] + +``` + +## cicero initialize + +`cicero initialize` initializes a clause. + +```md +cicero initialize + +initialize a clause + +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --sample path to the contract text [string] + --currentTime initialize with this current time [string] [default: null] + --warnings print warnings [boolean] [default: false] + +``` ## cicero archive -Creates a Cicero Template Archive (.cta) file from a template stored in a local directory. +`cicero archive` creates a Cicero Template Archive (`.cta`) file from a template stored in a local directory. + +```md +cicero archive + +create a template archive + +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --target the target language of the archive [string] [default: "ergo"] + --output file name for new archive [string] [default: null] + --warnings print warnings [boolean] [default: false] + +``` + +## cicero compile + +`cicero generate` generates code for a target platform. It loads a template from a directory on disk and then attempts to generate versions of the template model in the specified format. The available formats include: `Go`, `PlantUML`, `Typescript`, `Java`, and `JSONSchema`. + +```md +cicero compile + +generate code for a target platform -```sh - cicero archive +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --target target of the code generation [string] [default: "JSONSchema"] + --output path to the output directory [string] [default: "./output/"] + --warnings print warnings [boolean] [default: false] - Options: - --help Show help [boolean] - --version Show version number [boolean] - --template path to the directory with the template [string] - --archiveFile file name for the archive [string] - --verbose, -v [default: false] ``` +## cicero get -## cicero generate +`cicero get` saves local copies of external dependencies. -Loads a template from a directory on disk and then attempts to generate versions of the template model in the specified format. -The available formats include: `Go`, `PlantUML`, `Typescript`, `Java`, and `JSONSchema`. +```md +cicero get -```bash - cicero generate +save local copies of external dependencies - Options: - --help Show help [boolean] - --version Show version number [boolean] - --template path to the directory with the template - [string] [default: "."] - --format format of the code to generate - [string] [default: "JSONSchema"] - --outputDirectory output directory path [string] [default: "./output/"] - --verbose, -v [default: false] +Options: + --version Show version number [boolean] + --verbose, -v [default: false] + --help Show help [boolean] + --template path to the template [string] + --output output directory path [string] ``` diff --git a/docs/concerto-cli.md b/docs/concerto-cli.md index 336ffac5..6dd45150 100644 --- a/docs/concerto-cli.md +++ b/docs/concerto-cli.md @@ -3,7 +3,7 @@ id: concerto-cli title: Concerto CLI --- -Install the `@accordproject/concerto-cli` npm package to access the Concerto command line interface (CLI). After installation you can use the concerto command and its sub-commands as described below. +Install the `@accordproject/concerto-cli` npm package to access the Concerto command line interface (CLI). After installation you can use the `concerto` command and its sub-commands as described below. To install the Concerto CLI: ``` diff --git a/docs/ergo-cli.md b/docs/ergo-cli.md index aa3c2e1e..1605833f 100644 --- a/docs/ergo-cli.md +++ b/docs/ergo-cli.md @@ -3,90 +3,292 @@ id: ergo-cli title: Ergo CLI --- -To install the Ergo command-line interface (CLI): +Install the `@accordproject/ergo-cli` npm package to access the Ergo command line interface (CLI). After installation you can use the ergo command and its sub-commands as described below. -```term - npm install -g @accordproject/ergo-cli +To install the Ergo CLI: ``` +npm install -g @accordproject/ergo-cli@0.20.0 +``` + +This will install `ergo`, to compile and run contracts locally on your machine, and `ergotop`, which is a _read-eval-print-loop_ utility to write Ergo interactively. -This will install `ergoc`, the Ergo compiler, `ergorun` to run your contracts locally on your machine, and `ergotop` which is a _read-eval-print-loop_ utility to write Ergo interactively. +> In ergo-cli `0.20` release, `ergoc`, the Ergo compiler, and `ergorun`, used to run contracts locally on your machine, which were previously part of the `ergo-cli` npm package, have been merged into `ergo` commands. +> +> For more information about the changes that were made for the `0.20` release, please refer to our [Migrating from 0.13.\*](0.13to0.20.html) guide. -## ergoc + +## Ergo ### Usage -Compile an Ergo contract to a target platform +```md +ergo -```term - ergoc [options] [cto files] [ergo files] +Commands: + ergo draft create a contract text from data + ergo trigger send a request to the contract + ergo invoke invoke a clause of the contract + ergo initialize initialize the state for a contract + ergo compile compile a contract - Options: - --version Show version and exit - --target Target language (default: es6) (available: es5,es6,cicero,java) - --link Adds the Ergo runtime to the target code (for es5,es6 and cicero only) - --monitor Produce compilation time information - --warnings Print warnings - --help Show help and exit +Options: + --help Show help [boolean] + --version Show version number [boolean] + --verbose, -v [default: false] ``` -`ergoc` takes your input models (cto files) and input contracts (ergo files) and generates code for execution. By default it generates JavaScript code (ES6 compliant). +### ergo draft -### Examples +`ergo draft` allows you to create a contract text from data. Note that `--data` is a required field. -For instance, to compile the helloworld contract to JavaScript: +```md +## ergo draft +Usage: ergo draft --data [file] [ctos] [ergos] -```term - $ ergoc ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo - Compiling Ergo './examples/volumediscount/logic.ergo' -- creating './examples/volumediscount/logic.js' +Options: + --help Show help [boolean] + --version Show version number [boolean] + --verbose, -v [default: false] + --data path to the contract data [required] + --currentTime the current time + [string] [default: "2019-10-30T12:03:24+00:00"] + --wrapVariables wrap variables in curly braces [boolean] [default: false] + --template path to the template directory [string] [default: null] + --warnings print warnings [boolean] [default: false] ``` -To compile the helloworld contract to JavaScript and link the Ergo runtime for execution: +#### Example + +For example, using the `draft` command for the [Volume Discount example](https://github.com/accordproject/ergo/tree/master/examples/volumediscount) in the [Ergo Directory](https://github.com/accordproject/ergo): -```term - $ ergoc ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo --link - Compiling Ergo './examples/volumediscount/logic.ergo' -- creating './examples/volumediscount/logic.js' +```md +ergo draft --template ./examples/volumediscount --data ./examples/volumediscount/data.json ``` -To compile the helloworld contract to Java: +returns: -```term - $ ergoc ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo --target java - Compiling Ergo './examples/volumediscount/logic.ergo' -- creating './examples/volumediscount/logic.java' +```md +info: Volume-Based Card Acceptance Agreement [Abbreviated] + +This Agreement is by and between Card, Inc., a New York corporation, and you, the Merchant. +... +b) Discount. The Discount is determined according to the following table: + +| Annual Dollar Volume | Discount | +| Less than $1.0 million | 3.0% | +| $1.0 million to $10.0 million | 2.9% | +| Greater than $10.0 million | 2.8% | ``` -## ergorun +The variables specified in the `data.json` file (such as `firstVolume`: 1, `firstRate`: 3) are incorporated into the text of the contract (which can be found in the `./examples/volumediscount` template directory). -### Usage +> In general, the `data.json` files aren’t part of the template archive from the [Cicero Template Library](https://github.com/accordproject/cicero-template-library/tree/js-release-0.20/src). It is possible to generate one with [cicero parse](cicero-cli#cicero-parse). -Invoke an ergo contract -```term - ergorun --contract [file] --state [file] --request [file] [ctos] [ergos] +## ergo trigger +`ergo trigger` allows you to send a request to the contract. - Options: - --help Show help [boolean] - --version Show version number [boolean] - --contract path to the contract data [required] - --request path to the request data [array] [required] - --state path to the state data [string] [default: null] - --warnings print warnings [boolean] [default: false] - --contractname [required] - --verbose, -v [default: false] +```md +Usage: ergo trigger --data [file] --state [file] --request [file] [cto files] +[ergo files] + +Options: + --help Show help [boolean] + --version Show version number [boolean] + --verbose, -v [default: false] + --data path to the contract data [required] + --state path to the state data [string] [default: null] + --currentTime the current time[string] [default: "2019-10-30T20:18:28+00:00"] + --request path to the request data [array] [required] + --template path to the template directory [string] [default: null] + --warnings print warnings [boolean] [default: false] ``` -`ergorun` lets you invoke your Ergo contract. You need to pass the CTO and Ergo files, the name of the contract that you want to execute, and JSON files for: the contract parameters, the current state of the contract, and for the request. +### Example -### Examples +For example, using the `trigger` command for the [Volume Discount example](https://github.com/accordproject/ergo/tree/master/examples/volumediscount) in the [Ergo Directory](https://github.com/accordproject/ergo): -For instance, to send one request to the `volumediscount` contract: +```md +ergo trigger --template ./examples/volumediscount --data ./examples/volumediscount/data.json --request ./examples/volumediscount/request.json --state ./examples/volumediscount/state.json +``` -```term - $ ergorun ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo --contractname org.accordproject.volumediscount.VolumeDiscount --contract ./examples/volumediscount/contract.json --request ./examples/volumediscount/request.json --state ./examples/volumediscount/state.json - 02:33:50 - info: {"response":{"discountRate":2.8,"$class":"org.accordproject.volumediscount.VolumeDiscountResponse"},"state":{"$class":"org.accordproject.cicero.contract.AccordContractState","stateId":"1"},"emit":[]} +returns: + +```json +{ + "clause": "orgXaccordprojectXvolumediscountXVolumeDiscount", + "request": { + "$class": "org.accordproject.volumediscount.VolumeDiscountRequest", + "netAnnualChargeVolume": 10.4 + }, + "response": { + "$class": "org.accordproject.volumediscount.VolumeDiscountResponse", + "discountRate": 2.8, + "transactionId": "3024ea58-ad82-4c83-87b1-d8fea8436d49", + "timestamp": "2019-10-31T11:17:36.038Z" + }, + "state": { + "$class": "org.accordproject.cicero.contract.AccordContractState", + "stateId": "1" + }, + "emit": [] +} ``` +As the `request` was sent for an annual charge volume of 10.4, which falls into the third discount rate category (as specified in the `data.json` file), the `response` returns with a discount rate of 2.8%. + + +## ergo invoke +`ergo invoke` allows you to invoke a specific clause of the contract. The main difference between `ergo invoke` and `ergo trigger` is that `ergo invoke` sends data to a specific clause, whereas `ergo trigger` lets the contract choose which clause to invoke. This is why `--clauseName` (the name of the contract you want to execute) is a required field for `ergo invoke`. + +You need to pass the CTO and Ergo files (`--template`), the name of the contract that you want to execute (`--clauseName`), and JSON files for: the contract data (`--data`), the contract parameters (`--params`), the current state of the contract (`--state`), and the request. + If contract invocation is successful, `ergorun` will print out the response, the new contract state and any emitted events. +```md +Usage: ergo invoke --data [file] --state [file] --params [file] [cto files] +[ergo files] + +Options: + --help Show help [boolean] + --version Show version number [boolean] + --verbose, -v [default: false] + --clauseName the name of the clause to invoke [required] + --data path to the contract data [required] + --state path to the state data [string] [required] + --currentTime the current time[string] [default: "2019-10-30T20:18:57+00:00"] + --params path to the parameters [string] [required] [default: {}] + --template path to the template directory [string] [default: null] + --warnings print warnings [boolean] [default: false] +``` + +### Example + +For example, using the `invoke` command for the [Volume Discount example](https://github.com/accordproject/ergo/tree/master/examples/volumediscount) in the [Ergo Directory](https://github.com/accordproject/ergo): + +```md +ergo invoke --template ./examples/volumediscount --clauseName volumediscount --data ./examples/volumediscount/data.json --params ./examples/volumediscount/params.json --state ./examples/volumediscount/state.json +``` + +returns: + +```json +info: +{ + "clause": "orgXaccordprojectXvolumediscountXVolumeDiscount", + "params": { + "request": { + "$class": "org.accordproject.volumediscount.VolumeDiscountRequest", + "netAnnualChargeVolume": 10.4 + } + }, + "response": { + "$class": "org.accordproject.volumediscount.VolumeDiscountResponse", + "discountRate": 2.8, + "transactionId": "2a979363-56bc-48ff-a6b4-49994a848a0c", + "timestamp": "2019-10-31T11:22:37.368Z" + }, + "state": { + "$class": "org.accordproject.cicero.contract.AccordContractState", + "stateId": "1" + }, + "emit": [] +} +``` + +Although this looks very similar to what `ergo trigger` returns, it is important to note that `--clauseName volumediscount` was specifically invoked. + +## ergo initialize +`ergo initialize` allows you to obtain the initial state of the contract. This is the state of the contract without requests or responses. + +```md +Usage: ergo intialize --data [file] --params [file] [cto files] [ergo files] + +Options: + --help Show help [boolean] + --version Show version number [boolean] + --verbose, -v [default: false] + --data path to the contract data [required] + --currentTime the current time[string] [default: "2019-10-30T20:19:24+00:00"] + --params path to the parameters [string] [default: null] + --template path to the template directory [string] [default: null] + --warnings print warnings [boolean] [default: false] + +``` + +### Example + +For example, using the `initialize` command for the [Volume Discount example](https://github.com/accordproject/ergo/tree/master/examples/volumediscount) in the [Ergo Directory](https://github.com/accordproject/ergo): + +```md +ergo initialize --template ./examples/volumediscount --data ./examples/volumediscount/data.json +``` + +returns: + +```json +info: +{ + "clause": "orgXaccordprojectXvolumediscountXVolumeDiscount", + "params": { + }, + "response": null, + "state": { + "$class": "org.accordproject.cicero.contract.AccordContractState", + "stateId": "org.accordproject.cicero.contract.AccordContractState#1" + }, + "emit": [] +} +``` + +## ergo compile +`ergo compile` takes your input models (`.cto` files) and input contracts (`.ergo` files) and allows you to compile a contract into a target platform. By default, Ergo compiles to JavaScript (ES6 compliant) for execution. + + +```md +Usage: ergo compile --target [lang] --link --monitor --warnings [cto files] +[ergo files] + +Options: + --help Show help [boolean] + --version Show version number [boolean] + --verbose, -v [default: false] + --target Target platform (available: es5,es6,cicero,java) + [string] [default: "es6"] + --link Link the Ergo runtime with the target code (es5,es6,cicero + only) [boolean] [default: false] + --monitor Produce compilation time information [boolean] [default: false] + --warnings print warnings [boolean] [default: false] +``` + +### Example +For example, using the `compile` command on the [Volume Discount example](https://github.com/accordproject/ergo/tree/master/examples/volumediscount) in the [Ergo Directory](https://github.com/accordproject/ergo): + +```md +ergo compile ./examples/volumediscount/model/model.cto ./examples/volumediscount/logic/logic.ergo +``` + +returns: + +```md +Compiling Ergo './examples/volumediscount/logic/logic.ergo' -- './examples/volumediscount/logic/logic.js' +``` + +Which means a new `logic.js` file is located in the `./examples/volumediscount/logic` directory. + +To compile the contract to Javascript and **link the Ergo runtime for execution**: +```md +ergo compile ./examples/volumediscount/model/model.cto ./examples/volumediscount/logic/logic.ergo --link +``` + +returns: + +```md +Compiling Ergo './examples/volumediscount/logic/logic.ergo' -- './examples/volumediscount/logic/logic.js' +``` + + + ## ergotop (REPL) ### Starting the REPL @@ -96,9 +298,9 @@ If contract invocation is successful, `ergorun` will print out the response, the To start the REPL: ``` - $ ergotop - 02:39:37 - info: Logging initialized. 2018-09-25T06:39:37.209Z - ergo$ +$ ergotop +Welcome to ERGOTOP version 0.20.0 +ergo$ ``` It should print the prompt `ergo$` which indicates it is ready to read your command. For instance: @@ -122,12 +324,12 @@ If your expression is not valid, or not well-typed, it will return an error: ```ergo ergo$ return if true else "hello" - Parse error (at line 1 col 15). + Parse error (at line 1 col 15). return if true else "hello" ^^^^ ergo$ return if "hello" then 1 else 2 Type error (at line 1 col 10). 'if' condition not boolean. - return if "hello" then true else false + return if "hello" then 1 else 2 ^^^^^^^ ``` @@ -147,12 +349,12 @@ If what you are trying to write is too long to fit on one line, you can use `\` You can load CTO and Ergo files to use in your REPL session. Once the REPL is launched you will have to import the corresponding namespace. For instance, if you want to use the `compoundInterestMultiple` function defined in the `./examples/promissory-note/money.ergo` file, you can do it as follows: ```ergo -$ ergotop ./examples/promissory-note/money.ergo -08:45:26 - info: Logging initialized. 2018-09-25T12:45:26.481Z +$ ergotop ./examples/promissory-note/logic/money.ergo +Welcome to ERGOTOP version 0.20.0 + ergo$ import org.accordproject.ergo.money.* -ergo$ return compoundInterestMultiple(0.035, 100.0) +ergo$ return compoundInterestMultiple(0.035, 100) Response. 1.00946960405 : Double -ergo$ ``` ### Calling contracts @@ -160,20 +362,14 @@ ergo$ To call a contract, you first needs to _instantiate_ it, which means setting its parameters and initializing its state. You can do this by using the `set contract` and `call init` commands respectively. Here is an example using the `volumediscount` template: ```ergo -$ ergotop ./examples/volumediscount/model.cto ./examples/volumediscount/logic.ergo +$ ergotop ./examples/volumediscount/model/model.cto ./examples/volumediscount/logic/logic.ergo ergo$ import org.accordproject.cicero.contract.* ergo$ import org.accordproject.cicero.runtime.* ergo$ import org.accordproject.volumediscount.* -ergo$ set contract VolumeDiscount over TemplateModel{ \ - ... firstVolume: 1.0, \ - ... secondVolume: 10.0, \ - ... firstRate: 3.0, \ - ... secondRate: 2.9, \ - ... thirdRate: 2.8 \ - ... } -ergo$ call init(Request{}) +ergo$ set contract VolumeDiscount over VolumeDiscountContract {firstVolume: 1.0, secondVolume: 10.0, firstRate: 3.0, secondRate: 2.9, thirdRate: 2.8, contractId: "0", parties: none } +ergo$ call init() Response. unit : Unit -State. AccordContractState{stateId: "1"} : AccordContractState +State. AccordContractState{stateId: "org.accordproject.cicero.contract.AccordContractState#1"} : AccordContractState ``` You can then invoke clauses of the contract: @@ -192,4 +388,3 @@ Response. VolumeDiscountResponse{discountRate: 3.0} : VolumeDiscountResponse ergo$ send VolumeDiscountRequest{ netAnnualChargeVolume : 10.5 } Response. VolumeDiscountResponse{discountRate: 2.8} : VolumeDiscountResponse ``` - diff --git a/docs/markup-cicero.md b/docs/markup-cicero.md index 9c7d0639..e7cb75b5 100644 --- a/docs/markup-cicero.md +++ b/docs/markup-cicero.md @@ -3,19 +3,45 @@ id: markup-cicero title: Overview --- -## Principles +## Markup Templating for Smart Contracts -In order to make a clause executable, there needs to be a link to relate the template model to the natural language text that describes the legally enforceable clause. By inserting bindings to the template model into the natural language for the clause via the Accord Project markup language, we create what we call the template grammar. This determines what a syntactically valid clause may look like. +In order to make a contract or clause executable, there needs to be a link to relate the Template Model to the natural language text of the contract or clause. A markup language is used to insert bindings to the Template Model into the Text. Together, the marked-up Text and Template Model is referred to as the Template Grammar. The Template Grammar defines a syntactically valid contract or clause. The Accord Project markup language is called CiceroMark. It supports: -1. Rich text annotations based on [CommonMark](https://commonmark.org) -2. Template variables and blocks for structured content _in the style of_ [Handlebars](https://handlebarsjs.com) +1. Rich text annotations based on [CommonMark](https://commonmark.org) - a standard specification for Markdown +2. Template variables and blocks for structured content _in the style of_ [Handlebars](https://handlebarsjs.com), including [Concerto](https://www.accordproject.org/projects/concerto/) models 3. Formulas written as embedded [Ergo](https://docs.accordproject.org/docs/logic-ergo.html) expressions -In a nutshell, CiceroMark is similar to Handlebars with two key differences: +CiceroMark is similar to Handlebars with two key differences: - it is a template language for CommonMark rather than HTML - it uses Ergo as an expression language rather than JavaScript + +### An Extensible Framework for Contracts + +The CiceroMark markup language is used to turn contracts from static, unstructured, text into structured, machine-readable, documents. Contractual documents may take one of three evolutionary forms: + +1. Text: Natural language formats such as .docx or .pdf +2. Text + Model: Defining variables in text using data models, capable of being rendered as structured data objects in formats such as JSON +3. Text + Model + Logic: Adding logic expressions and functions to structured data objects to define dynamic functionality, such as calculating values + +The markup language is intended to act as a standard format for expressing contracts in a natively computable manner; namely forms 2 and 3. It is built to be compatible and extensible with other industry standard schemas and domain models: + +- [FpML](https://www.fpml.org/) for sharing derivatives data - see [FpML5 Confirmation Model](https://models.accordproject.org/fpml5/confirmation.html) +- [CommonMark](https://commonmark.org/) - see [CommonMark Model](https://models.accordproject.org/markdown/commonmark.html) +- [ISDA CDM](https://www.isda.org/2019/10/14/isda-common-domain-model/) - see [CDM Model](https://models.accordproject.org/isda/org.isda.cdm.html) +- IETF standards e.g. [RFC 5545](https://tools.ietf.org/html/rfc5545) - see [Calendar Model](https://models.accordproject.org/calendar/calendar.html) +- ISO standards e.g. [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) - see [Geo Model](https://models.accordproject.org/geo.html) + +As such, CiceroMark acts as an extensible framework for computable contracts; providing support for existing and future standards, schemas, and models. It is intended that CiceroMark will be used as a foundation upon which extensions for various contract types are built as industries increasingly define domain models and support smart contracts. + +### Features + +- Extensibility: New industry models and [statements](https://docs.accordproject.org/docs/logic-module.html) can be easily defined to extend the functionality of the markup language for new domains, contract types, industry standards etc. +- Compatibility: Works with industry standard schemas and domain models +- Understandability: Extends existing, established, templating approaches (e.g. Handlebars) +- Modularity: **WIP** + ## Example Here is an example using a simple fixed-rate interest clause. @@ -54,7 +80,7 @@ and monthly payments of {{I'm not sure which amount right now}} You can use the Cicero command-line to parse that text and extract the variables for the template: ```js -$ cicero parse --out data.json +$ cicero parse --out data.json 09:09:15 - info: Using current directory as template folder 09:09:15 - info: Loading a default sample.md file. 09:09:18 - info: Creating file: data.json @@ -70,9 +96,8 @@ $ cicero parse --out data.json Note that parsing is resilient to variations in the markdown annotations. In the above example, the template uses `*fixed interest*` to indicates italics, but the sample uses `_fixed interest_`. Parsing still succeeds since those are equivalent. -Note also that the sample uses `{{ ... }}` to indicate the part of the text corresponding to expressions. Those need not be +Note also that the sample uses `{{ ... }}` to indicate the part of the text corresponding to expressions. Those need not be **TBD** ## Drafting contract text from data - diff --git a/website/i18n/en.json b/website/i18n/en.json index 40017f98..33697ec2 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -695,7 +695,7 @@ "categories": { "Introduction": "Introduction", "Getting Started": "Getting Started", - "Legal-Tech Tutorials": "Legal-Tech Tutorials", + "Beginners Tutorials": "Beginners Tutorials", "Developers Tutorials": "Developers Tutorials", "Template Guides": "Template Guides", "About Version 0.20": "About Version 0.20", diff --git a/website/sidebars.json b/website/sidebars.json index 400d8e7c..519949ea 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -2,7 +2,7 @@ "docs": { "Introduction": ["accordproject", "accordproject-lawyers", "accordproject-developers", "accordproject-concepts"], "Getting Started": ["started-studio", "started-installation", "started-helloworld", "started-resources"], - "Legal-Tech Tutorials": [ + "Beginners Tutorials": [ { "type": "subcategory", "label": "Authoring in Template Studio", From 5e6f6c19c07ad69e3eaf376151fe063c448f1921 Mon Sep 17 00:00:00 2001 From: Katie Date: Thu, 31 Oct 2019 14:16:00 +0000 Subject: [PATCH 2/2] made minor changes to cicero-cli and ergo-cli Signed-off-by: Katie --- docs/cicero-cli.md | 2 +- docs/ergo-cli.md | 2 +- docs/markup-cicero.md | 20 +------------------- website/sidebars.json | 2 +- 4 files changed, 4 insertions(+), 22 deletions(-) diff --git a/docs/cicero-cli.md b/docs/cicero-cli.md index 6d170bb0..f6e788c8 100644 --- a/docs/cicero-cli.md +++ b/docs/cicero-cli.md @@ -7,7 +7,7 @@ Install the `@accordproject/cicero-cli` npm package to access the Cicero command To install the Cicero CLI: ``` -npm install -g @accordproject/cicero-cli@0.20.0 +npm install -g @accordproject/cicero-cli ``` ## Usage diff --git a/docs/ergo-cli.md b/docs/ergo-cli.md index 1605833f..ba346a30 100644 --- a/docs/ergo-cli.md +++ b/docs/ergo-cli.md @@ -7,7 +7,7 @@ Install the `@accordproject/ergo-cli` npm package to access the Ergo command lin To install the Ergo CLI: ``` -npm install -g @accordproject/ergo-cli@0.20.0 +npm install -g @accordproject/ergo-cli ``` This will install `ergo`, to compile and run contracts locally on your machine, and `ergotop`, which is a _read-eval-print-loop_ utility to write Ergo interactively. diff --git a/docs/markup-cicero.md b/docs/markup-cicero.md index e7cb75b5..77bf2f20 100644 --- a/docs/markup-cicero.md +++ b/docs/markup-cicero.md @@ -17,24 +17,6 @@ CiceroMark is similar to Handlebars with two key differences: - it uses Ergo as an expression language rather than JavaScript -### An Extensible Framework for Contracts - -The CiceroMark markup language is used to turn contracts from static, unstructured, text into structured, machine-readable, documents. Contractual documents may take one of three evolutionary forms: - -1. Text: Natural language formats such as .docx or .pdf -2. Text + Model: Defining variables in text using data models, capable of being rendered as structured data objects in formats such as JSON -3. Text + Model + Logic: Adding logic expressions and functions to structured data objects to define dynamic functionality, such as calculating values - -The markup language is intended to act as a standard format for expressing contracts in a natively computable manner; namely forms 2 and 3. It is built to be compatible and extensible with other industry standard schemas and domain models: - -- [FpML](https://www.fpml.org/) for sharing derivatives data - see [FpML5 Confirmation Model](https://models.accordproject.org/fpml5/confirmation.html) -- [CommonMark](https://commonmark.org/) - see [CommonMark Model](https://models.accordproject.org/markdown/commonmark.html) -- [ISDA CDM](https://www.isda.org/2019/10/14/isda-common-domain-model/) - see [CDM Model](https://models.accordproject.org/isda/org.isda.cdm.html) -- IETF standards e.g. [RFC 5545](https://tools.ietf.org/html/rfc5545) - see [Calendar Model](https://models.accordproject.org/calendar/calendar.html) -- ISO standards e.g. [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) - see [Geo Model](https://models.accordproject.org/geo.html) - -As such, CiceroMark acts as an extensible framework for computable contracts; providing support for existing and future standards, schemas, and models. It is intended that CiceroMark will be used as a foundation upon which extensions for various contract types are built as industries increasingly define domain models and support smart contracts. - ### Features - Extensibility: New industry models and [statements](https://docs.accordproject.org/docs/logic-module.html) can be easily defined to extend the functionality of the markup language for new domains, contract types, industry standards etc. @@ -80,7 +62,7 @@ and monthly payments of {{I'm not sure which amount right now}} You can use the Cicero command-line to parse that text and extract the variables for the template: ```js -$ cicero parse --out data.json +$ cicero parse --output data.json 09:09:15 - info: Using current directory as template folder 09:09:15 - info: Loading a default sample.md file. 09:09:18 - info: Creating file: data.json diff --git a/website/sidebars.json b/website/sidebars.json index 519949ea..868ec6fe 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -2,7 +2,7 @@ "docs": { "Introduction": ["accordproject", "accordproject-lawyers", "accordproject-developers", "accordproject-concepts"], "Getting Started": ["started-studio", "started-installation", "started-helloworld", "started-resources"], - "Beginners Tutorials": [ + "User Tutorials": [ { "type": "subcategory", "label": "Authoring in Template Studio",