Mixing data types

While drafting clauses in ClauseBase is certainly not “programming” in the traditional sense, ClauseBase borrows some best-practices from traditional programming languages. Legal experts who have never done any traditional programming are often confused by these practices.

One such issue is the concept of data types — aka the issue of not mixing apples and oranges. This page deliberately takes a deep-dive into dealing with these types, to fully explain how they work in ClauseBase.

Natural language versus conditions & calculations

A first important idea to grasp is the distinction between natural language mode and conditions/calculations mode.

The standard mode in ClauseBase is the natural language mode. This is the mode you will implicitly arrive in when starting to type something in a clause. It will consist of “human” language stuff, such as words in English/French/Dutch, punctuation and numbering, etc. For example, the following clause entirely consists of the natural language mode elements:

A clause that consists entirely of natural language mode elements will be completely static, i.e. aside from the numbering and formatting of the clause, this clause will not change appearance. To insert dynamic elements, you insert conditions and calculations, for example:

As soon as you type in an opening accolade { you will leave the natural language mode, and enter either

• the condition mode, for which the result’s type is always true or false); or
• the calculation mode (for which the result’s type depends on the kind of calculation being made).

In the example above, #contract^value < 500 EUR and #contract^value < 2000 EUR are written in the condition mode, while apples^amount * #apples^unit-price is written in the calculation mode.

After the closing accolade }you will in any case leave these modes, and return to the natural language mode. However, the switch between the modes is more complex than just looking at the opening and closing accolade. For example, in paragraph 1. above, the parts between the colon (:) and the vertical bar (|) are once again in the natural language mode, i.e. the words low and medium and high.

Calculation mode

As the name implies, calculation mode expects to perform calculations. The input to these calculations consists of a mix of countable elements and optional operators — e.g. 5 + 24 or 5 * 4.5 EUR, but also 12 months * 4 or 2020_11_23 + 3 days, because you can perform interesting calculations with durations and dates.

Instead of using directly countable elements, you can also work with elements that ultimately boil down to numbers. For example, in apples^amount * #apples^unit-price, the datafields “amount” and “unit-price” can be assumed to contain countable things. When, for example, the number 5 would be assigned to apples^amount and the #apples^unit-price would be assigned the value 0.4 EUR, ClauseBase will happily perform the calculation for you and return the result (2 EUR).

Note that natural text cannot, as such, be used in calculation mode. After all, text is — as such such — not countable. It does not make sense to, for example, perform a calculation to divide the words “the Buyer buys an apple” by the words “the Seller sells a pear”.

Condition mode

Writing in the condition mode will be writing in calculation mode, with one exception. Condition mode is meant to ultimately result in true or false, and will therefore contain a left side with a calculation, a comparison operator and a right side with yet another calculation.

For example, in the condition apples^amount * #apples^unit-price < 2000 EUR, you will see a left side (containing a calculation on apples), a comparison-operator (smaller than <), and a right side (with a single currency-value).

Data types

In ClauseBase, as in most programming languages, you can only calculate with elements of the same data type, and you can only compare elements of the same data type. For example, it does not make sense to add 25 EUR to a date, or to compare the text “alpha” to the duration of 5 months.

ClauseBase offers the following basic data types:

In addition, the following special data types are also offered.

The three different modes result in three different data types:

Supported currencies

ClauseBase currently supports the following currencies:

Conversions between data types

While it is not possible to perform calculations or comparisons with elements of different data types, it is possible to convert an element to another data type. This conversion can either be done explicitly or implicitly.

Explicit conversions

Explicit conversions can be achieved using special functions. For example, the special function @extract-number will take a currency number (e.g., 5.5 EUR) and return the floating point number (5.5). Similarly, the sole purpose of the special function @str is to convert the argument passed to it into text — e.g. @str(3 months) will, depending on the styling settings, result in the text 3 months when the active language is English.

Most special functions will perform something more than solely converting an argument from one data type to another data type. Examples:

• @round and @floor will convert the floating point number passed to them, and then either round that number or truncate the decimal part, returning a whole number
• @comma-split will take a text element and return a list element that contains individual text elements (e.g. @comma-split("alpha, beta, gamma") will return a list with text elements "alpha", "beta" and "gamma".

Implicit conversions of basic data types

It would be cumbersome to always have to explicitly convert data types — e.g., imagine that in order to take 5.5 times the duration of a contract, you would have to write 5.5 * @float(@months-in(#contract^duration))

To avoid these situations, ClauseBase will implicitly perform conversions for you when no ambiguity is involved:

• (*) When mixing a date with a duration, note that the order and operation matters. The conversion will only be applied with date +/- duration. If you change the ordering (e.g., duration first) or the operation (e.g. multiplication), the result will be an error.
  
• (**) When mixing a list with, the order and operation matters: the conversion will only be applied with list +/- element, not with element +/- list.
  • When using the - operator, the element(s) at the right side are removed from the list at the left side. For example, @list("alpha", "beta") - "alpha" and @list("alpha", "beta") - @list("alpha") both result in @list("beta").
  • When using the + operator, the result depends on the right-side:
    • If both the left & right side are lists, then the result will be a concatenation of the two lists, with all the elements of the right list appended to the left list, irrespective of whether they were already present in the left list. For example, @list("alpha", "beta", "gamma") + @list("alpha", "delta") will result in @list("alpha", "beta", "gamma", "alpha", "delta"). (If you want a union of the list, where elements-already-present are not added again, use the @union special function instead of +).
    • If the right side is not a list, then it will be added as a new element of the left list, irrespective of whether the right side element was already present in the list. For example, @list("alpha", "beta") + "alpha" will result in @list("alpha", "beta", "alpha"). (If you want a union of the list and the single element, where the right-side element is not added again to the left list, use the @union special function instead of +).

Implicit conversions of undefined

When using datafields, values will often not be present, because they have not (yet) been filled in by the end-user. Within a calculation/condition, to avoid errors, ClauseBase will try to convert this undefined value to a sensible default value:

Implicit conversions to true/false in a condition

In condition mode, the following implicit conversions are carried out to convert a data type to true/false:

Note that in an if-then-else condition, you can omit the operator and right-hand side of the comparison for the sake of brevity; ClauseBase will then automatically insert = true. For example:

• Instead of writing {#contract^is-dutch-law = true: ... } you can also write {#contract^is-dutch-law: ... }. If the datafield is-dutch-law is a true/false datafield, then no implicit conversions will occur.
• Instead of writing {#contract^value > 0: ... } you can also write {#contract^value = true: ... } or the shorter version{#contract^value: ... }. In both of these cases, the contract-value whole number datafield will be converted into a true/false, meaning it will result in true if a non-zero value is assigned to this datafield; it will instead result in false when no value is assigned at all, or when the value that is assigned to this datafield, is equal to zero.

Implicit duration conversions

When combining duration elements of different units in a calculation, conversions may be necessary — e.g., when you add 2 days to 3 months. You should be aware that such conversions will in many cases result in rounding errors and unexpected results, because a duration does not contain any context about the month or year it relates to.

ClauseBase will convert durations with different units into the lowest time unit, e.g. year + months will be converted to months, year + days will be converted into days, and months + weeks will be converted into weeks. ClauseBase tries to use sensible averages during this conversion, but unexpected results are bound to happen due to the lack of context.

The bottom line is that you should try to avoid these implicit conversions as much as possible.

Implicit conversions to clause text

ClauseBase allows you insert a datafield directly into natural text. For example:

While perhaps not immediately obvious, this is also a situation where apples (clause text) are combined with oranges (number datafield). To avoid that you would have to insert all kinds of ugly codes to allow this, ClauseBase will implicitly convert this datafield into clause text for you.

In most situations, this conversion will be very straightforward. However, do note the following.

• A (whole/floating point/currency) number and a date value be converted into text in accordance with the locale styling rules (e.g., for the decimals style, currency symbol placement, short/long date format, etc.).
• A true/false value will get translated — e.g., Alpha {true}. will be converted into Alpha true in English and Alpha vrai in French.
• A list value will have its elements printed consequentially with spaces in between — e.g. @list("alpha", "beta", "gamma") will be converted into alpha beta gamma. If you want to have comma’s plus and/or etc. in such list, or perhaps convert it into a bullet-list, then you need to use one of the special functions — e.g., @enumerate-andor(@list("alpha", "beta", "gamma")).

Avoided implicit conversions

Some conversions are deliberately not performed, because they would be ambiguous:

• Adding a (whole/floating/currency) number to a duration or date. For example, 3 months + 3 results in an error because it will be difficult for the software to figure out whether you want the result to be a duration (6 months) or a whole number instead (6).
• Adding a number to a date. For example, 2020_04_07 + 3 results in an error, because it is not clear whether you would like to add 3 years, 3 months, 3 weeks or 3 days instead.

Other conversions are deliberately not performed because they make no sense:

• Mixing text and whole/floating/currency numbers. It will usually be obvious that this does not make sense — e.g. "alpha" + 6 — but this may not always be intuitive to those new to ClauseBase.
  
  For example, if you create a text datafield #contract^value, then ClauseBase will treat the contents of this datafield as text, and issue an error when you try to do a calculation such as #contract^value * 2. This error will make perfect sense when the end-user would type in “real” text (such as the word “Paris”), because you can obviously not multiply Paris by two. However, when an end-user would type in a number (e.g., 3500), then it will not be so obvious why the software is complaining.

Disallowed operations

While not a data type conversion issue, you should also note that some operations are not allowed between elements of the same data type:

• You cannot mix different currencies — e.g., adding {200 EUR + 300 USD} results in an error.
• You cannot add dates to each other — e.g. {2020_04_03 + 2020_05_3} results in an invalid operation error.

Dealing with the data type of if/then/else

An if/then/else construction will normally result in clause text. For example,

1. Upon drafting @CONTRACT, the parties agreed to have @CONTRACT screened by the authorities. If @CONTRACT would turn out to be ...

CONTRACT = {#contract^with-annexes: this Employment And Restructuring Contract (ERC) including its annexes | else: this ERC}

The contents of the internal snippet CONTRACT will be clause text, because its sole element is an if/then/else construction between curly braces. Such clause text can be inserted into the main body of the clause without any conversion being necessary.

However, it is also possible to use the if/then/else construction to return other data values. You can do this by wrapping the content of the if/then/else after the colon (:) between curly braces. For example:

1. Buyer will pay an amount equal to {@INTEREST * 1.5} before 1st January. If this payment is not successfully performed, it will be automatically increased to {@INTEREST * 2}.

INTEREST = {#contract^jurisdiction = "dutch": {0.05 * #contract^value} | else: {0.08 * #contract^value} }

It is interesting to analyse why you will get a “value is not a number” error when you omit the two pairs of curly braces in the if/then/else construction:

1. Buyer will pay an amount equal to {@INTEREST * 1.5} before 1st January. If this payment is not successfully performed, it will be automatically increased to {@INTEREST * 2}.

INTEREST = {#contract^jurisdiction = "dutch": 0.05 * #contract^value | else: 0.08 * #contract^value }

The reason is that ClauseBase will do the following:

• When encountering the {@INTEREST * 1.5}, it will replace the @SNIPPET with the contents of the internal snippet, arriving at {#contract^jurisdiction = "dutch": 0.05 * #contract^value | else: 0.08 * #contract^value } * 1.5
• It will then execute the if/then/else construction, and check whether the contract’s jurisdiction is equal to “dutch”. Assuming this is indeed the case, ClauseBase will notice that the associated fragment it has to insert into the main part of the clause is 0.05 * #contract^value.
• Because this fragment is not wrapped in curly braces, ClauseBase will treat the fragment as clause text. For example, if the contract’s value is currently set to 1000, and the current styling happens to be metric, it would convert the fragment into the text “0.05 * 1.000” . Notice that:
  • because the fragment is treated as clause text, ClauseBase will treat the 0.05 literally, i.e. not consider it to be a number. Accordingly, despite the fact that the styling settings are set to metric (so that a floating point number such as 0.05 would be printed with a comma as “0,05”), ClauseBase will print it as “0.05”
  • the contract’s value (1000) is a whole number that is inserted into clause text, and will therefore get converted to clause text, respecting all the styling settings (such as the metric style’s dot between the 1 and the three zeroes)
• Next, it will try to multiply the clause text “0.05 * 1.000” by the number 1.5, which obviously does not make sense because you cannot multiply text by a number. It will therefore issue a warning “value is not a number”.

Pursuant to article 3§4 of the Civil Code, #Buyer shall ...

Examples

#Buyer shall pay interest equal to @days-between(@DATE, @today)

DATE = {#contract^prolonged: #contract^prolongation-date | else: #contract^start-date}

#Buyer shall pay interest equal to @days-between(@DATE, @today)

DATE = {#contract^prolonged: {#contract^prolongation-date} | else: {#contract^start-date}}