Support for Dynamic Template Grammars with Expressions

[jeromesimeon]

A syntax proposal is available at #392

It would be quite nice to provide finer grained control of the contract text by embedding logic in the template.

To illustrate some of the possible benefits/usecases, here are a few examples:

Handling Text Dependencies:

Template:

This is a fixed interest loan to the amount of [{loanAmount}]
at the yearly interest rate of [{rate}]%
with a loan term of [{loanDuration}],
and montly payments of {{monthlyPaymentFormula(loanAmount,rate,loanDuration)}}

For the contract data:

{
  "$class": "org.accordproject.loan.Contract",
  "loanAmount": 100000,
  "rate": 2.5,
  "loanDuration": {
    "amount": 15,
    "unit": "years"
  }
}

The text of the contract will be:

This is a fixed interest loan to the amount of 100000
at the yearly interest rate of 2.5%
with a loan term of 10 years,
and montly payments of {{667}}

Such dependencies can be found in legal documents such as loans or in more complex forms in e.g., interest swaps: https://www.sec.gov/Archives/edgar/data/1508478/000119312511077213/dex1021.htm

Constructing Lists (#20):

Template:

Exhibit B
Authorized Licensed Products and Territory
Products:
{{ foreach p in products return {{- {{ p.productDescription }}\n}} }}
Territory:
{{ foreach c in countries return {{- {{ c }}\n}} }}

For the contract data:

{
  "$class": "org.accordproject.trademark",
  "products": [
    "Men’s footwear", "Men’s hosiery", "Men’s belts",
    "Men’s wallets", "Men’s documents cases and Men’s business card cases",
    "Men’s shave kits", "Men’s key fobs", "Men’s money clips"
  ],
  "countries": [
    "United States of America including its territories and possessions",
    "Canada",
    "UAE"
  ]
}

The text of the contract will be:

Exhibit B
Authorized Licensed Products and Territory
Products:
- Men’s footwear
- Men’s hosiery
- Men’s belts
- Men’s wallets
- Men’s documents cases and Men’s business card cases
- Men’s shave kits
- Men’s key fobs
- Men’s money clips

Territory:
- United States of America including its territories and possessions
- Canada
- UAE

Constructing Tables (#20):

Template:

Volume-Based Card Acceptance Agreement [Abbreviated]

This Agreement is by and between Card, Inc., a New York corporation, and you, the Merchant. By accepting the Card, you agree to be bound by the Agreement. 
Discount means an amount that we charge you for accepting the Card, which amount is: ...

| Annual Dollar Volume      | Discount             |
{{ foreach dr in discountRates
   return
     let lessThan = dr.volumeUpTo ?? 0;
     let greaterThan = dr.volumeUpTp ?? infinity;
     {{| ${{ lessThan }} to ${{ greaterThan }} | {{ dr.rate }} |}} }}

_______________________					_____________________
 Card, Inc.	

For the contract data:

{
  "discountRates" : [
  { "volumeAbove" : null,
    "volumeUpTo" : 1000,
    "rate" : 3.00 },
  { "volumeAbove" : 1000,
    "volumeUpTo" : 10000,
    "rate" : 2.90 },
  { "volumeAbove" : 10000,
    "volumeUpTo" : null,
    "rate" : 2.80 }
  ]
}

The text of the contract will be:

Volume-Based Card Acceptance Agreement [Abbreviated]

This Agreement is by and between Card, Inc., a New York corporation, and you, the Merchant. By accepting the Card, you agree to be bound by the Agreement. 
Discount means an amount that we charge you for accepting the Card, which amount is: ...

| Annual Dollar Volume      | Discount             |
| $0 than $1000             | 3.00%                |
| $1000 to $10000           | 2.90%                |
| $10000 to $infinity       | 2.80%                |

Handling Optional Text:

Template:

Late Delivery and Penalty. In case of delayed delivery{{ if forceMajeure then {{ except for Force Majeure cases,}} else ""}} [{seller}] (the Seller) shall pay to [{buyer}] (the Buyer) for every [{penaltyDuration}] of delay penalty amounting to [{penaltyPercentage}]% of the total value of the Equipment whose delivery has been delayed. Any fractional part of a [{fractionalPart}] is to be considered a full [{fractionalPart}]. The total amount of penalty shall not however, exceed [{capPercentage}]% of the total value of the Equipment involved in late delivery. If the delay is more than [{termination}], the Buyer is entitled to terminate this Contract.

For the contract data:

{
  "$class": "org.accordproject.latedeliveryandpenalty.LateDeliveryAndPenaltyContract",
  "contractId": "c0f8c55b-a8de-4cb1-9991-632b92308920",
  "buyer": {
    "$class": "org.accordproject.cicero.contract.AccordParty",
    "partyId": "Steve"
  },
  "seller": {
    "$class": "org.accordproject.cicero.contract.AccordParty",
    "partyId": "Dan"
  },
  "forceMajeure": true,
  "penaltyDuration": {
    "$class": "org.accordproject.time.Duration",
    "amount": 2,
    "unit": "days"
  },
  "penaltyPercentage": 10.5,
  "capPercentage": 55,
  "termination": {
    "$class": "org.accordproject.time.Duration",
    "amount": 15,
    "unit": "days"
  },
  "fractionalPart": "days"
}

The text of the contract will be:

Late Delivery and Penalty. In case of delayed delivery except for Force Majeure cases, "Dan" (the Seller) shall pay to "Steve" (the Buyer) for every 2 days of delay penalty amounting to 10.5% of the total value of the Equipment whose delivery has been delayed. Any fractional part of a days is to be considered a full days. The total amount of penalty shall not however, exceed 55% of the total value of the Equipment involved in late delivery. If the delay is more than 15 days, the Buyer is entitled to terminate this Contract.

Handling Optional Text with Parameters (#17):

Template:

Late Delivery and Penalty. In case of delayed delivery{{ if forceMajeure then {{ except for Force Majeure cases in the {{forceMajeureWindow}} before the delivery date,}} else ""}} [{seller}] (the Seller) shall pay to [{buyer}] (the Buyer) for every [{penaltyDuration}] of delay penalty amounting to [{penaltyPercentage}]% of the total value of the Equipment whose delivery has been delayed. Any fractional part of a [{fractionalPart}] is to be considered a full [{fractionalPart}]. The total amount of penalty shall not however, exceed [{capPercentage}]% of the total value of the Equipment involved in late delivery. If the delay is more than [{termination}], the Buyer is entitled to terminate this Contract.

For the contract data:

{
  "$class": "org.accordproject.latedeliveryandpenalty.LateDeliveryAndPenaltyContract",
  "contractId": "c0f8c55b-a8de-4cb1-9991-632b92308920",
  "buyer": {
    "$class": "org.accordproject.cicero.contract.AccordParty",
    "partyId": "Steve"
  },
  "seller": {
    "$class": "org.accordproject.cicero.contract.AccordParty",
    "partyId": "Dan"
  },
  "forceMajeure": true,
  "forceMajeureWindow": {
    "$class": "org.accordproject.time.Duration",
    "amount": 7,
    "unit": "days"
  },
  "penaltyDuration": {
    "$class": "org.accordproject.time.Duration",
    "amount": 2,
    "unit": "days"
  },
  "penaltyPercentage": 10.5,
  "capPercentage": 55,
  "termination": {
    "$class": "org.accordproject.time.Duration",
    "amount": 15,
    "unit": "days"
  },
  "fractionalPart": "days"
}

The text of the contract will be:

Late Delivery and Penalty. In case of delayed delivery except for Force Majeure cases in the 7 DAYS before the delivery date, "Dan" (the Seller) shall pay to "Steve" (the Buyer) for every 2 days of delay penalty amounting to 10.5% of the total value of the Equipment whose delivery has been delayed. Any fractional part of a days is to be considered a full days. The total amount of penalty shall not however, exceed 55% of the total value of the Equipment involved in late delivery. If the delay is more than 15 days, the Buyer is entitled to terminate this Contract.

[jeromesimeon]

Handling Complex Data:

Template:

Delivery shall be sent to:
{{
  enforce buyerAddress.streetAddress != none
  and buyerAddress.addressCountry = some("USA")
  and buyerAddress.postalCode != none
  and buyerAddress.addressRegion != none;
  and buyerAddress.addressLocality != none;
  {{{{ buyer }}
{{ buyerAddress.streetAddress }}{{ match buyerAddress.postOfficeBoxNumber with let? po then " (PO Box: " ++ po ++ ")" else "" }}
{{ buyerAddress.addressLocality }}, {{ buyerAddress.addressRegion }} {{ buyerAddress.postalCode }}}}
}}

For the contract data:

{
  "$class": "org.accordproject.latedeliveryandpenalty.LateDeliveryAndPenaltyContract",
  "contractId": "c0f8c55b-a8de-4cb1-9991-632b92308920",
  "buyer": {
    "$class": "org.accordproject.cicero.contract.AccordParty",
    "partyId": "Steve"
  },
  "buyer": {
    "$class": "org.accordproject.cicero.contract.AccordParty",
    "partyId": "Dan"
  },
  "buyerAddress": {
    "streetAddress": "555 Main Street",
    "postalCode": "10001",
    "postOfficeBoxNumber": null,
    "addressRegion": "NY",
    "addressLocality": "New York",
    "addressCountry": "USA"
  }
}

The text of the contract will be:

Delivery shall be sent to:
Dan
555 Main Street
New York, NY 10001

For the contract data:

{
  "$class": "org.accordproject.latedeliveryandpenalty.LateDeliveryAndPenaltyContract",
  "contractId": "c0f8c55b-a8de-4cb1-9991-632b92308920",
  "buyer": {
    "$class": "org.accordproject.cicero.contract.AccordParty",
    "partyId": "Steve"
  },
  "buyer": {
    "$class": "org.accordproject.cicero.contract.AccordParty",
    "partyId": "Dan"
  },
  "buyerAddress": {
    "streetAddress": "555 Main Street",
    "postalCode": "55WI555",
    "postOfficeBoxNumber": null,
    "addressRegion": null,
    "addressLocality": "London",
    "addressCountry": "UK"
  }
}

Attempting to generate the text of the contract will result in an enforce error.

[jeromesimeon]

Note that an approach based on expressions within templates may also cover #296

[jeromesimeon]

Implemented syntax uses: {{% expression %}} and is part of the 0.20 release. I'm closing this issue as done. Any other question or problems specific to dynamic templates support can be open as new issues.