Snippets

Snippets are ways of making writing new clauses more efficient and/or more readable. They are re-usable pieces of text that can either be used inside one clause (internal snippets) or as part of all clauses (external snippets).

Snippets work similar to variables in mathematics or programming languages. They are referenced by a name and represent a piece of text.

Internal snippets

Internal snippets are pieces of text that can be used multiple times inside the same clause. They will not be available outside the clause where they are defined.

Internal snippets are defined at the bottom of a clause as follows: NAME-SNIPPET = content snippet. Insert the name by which you want to refer to the snippet in all caps, e.g. NAME-SNIPPET. Then, after the equals symbol (=), insert the text you want to be inserted in all places where the snippet is referenced.

Referring to an internal snippet (i.e. showing ClauseBase where the snippet text should be placed) is done by taking the name of the snippet and adding an “at” symbol @. For example:

1. This is @SNIPPET.

SNIPPET = a snippet, which will be replaced by the text defined at the bottom of the clause grammar

Will result in the following:

Snippets may contain all types of text, datafields or conditions. They can even refer to other (internal or external) snippets, making multi-tiered snippets possible.

External snippets

External snippets are similar to internal snippets. They are, however, defined and referenced differently.

Defining an external snippet

Because an external snippet should be made available to all clauses inside your library, it should be defined outside a normal clause. It is defined by creating a normal clause which will be used as a kind of special purpose vehicle.

Naming an external snippet follows the same rules as the naming of a concept. The file name of the clause that will serve as an external snippet may, e.g., not contain any spaces as that would make referring to the external snippet impossible (see below). It is not necessary to use all caps when naming an external snippet.

Enter the text for your snippet as the clause’s content body.

Referring to an external snippet

While internal snippets are referenced by simply adding a @-prefix, external snippets are referenced differently. After the @, a hashtag has to be added as well: @#. For example: @#external-snippet.

Purposes

Efficiency and consistency

Snippets can make writing clauses more efficient and consistent. Using snippets, you can easily create a piece of text that is used in many spots at once. This also saves time when that piece of text must be changed or updated: just change the snippet and all places where that snippet is referenced will automatically incorporate that change (which is much the same way a library clause functions).

Readability

A snippet can also make reading clause grammar more easy. For example, conditional text may become very complex if multiple conditions have to be evaluated at the same time. Long/complex grammar may make the structure of the clause grammar difficult to read. Replacing the most complex bits of grammar with snippets will improve readability.

Bonus tip: snippets within snippets

This may not be obvious at first sight, but you can actually use snippets within snippets, any level deep. For example, you can write:

#Buyer shall purchase @GOODS-OR-SERVICES from #seller.

GOODS-OR-SERVICES = {#contract^goods-sold = true: @GOODS | #contract^services-sold: @SERVICES}

GOODS = #goods in perfect condition, at @GOODS-PRICE, 

GOODS-PRICE = {#goods^price > 500 EUR: the extremely low price of #goods^price | else: the price of #goods^price}

SERVICES = #services that meet the specified criteria

From a mental point of view, all these snippets facilitate easier reading, because you don’t have to nest conditions and curly braces, which becomes difficult to keep track of as from the second level deep.

Example

The following grammar is rather difficult to read:

1. <#Seller> shall use <its: seller> best efforts to satisfy or procure the satisfaction of #conditions-precedent in {AND | {"cp-change-of-control" in #conditions-precedent^!seller-responsibility: §cp-change-of-control} | {"cp-competition-clearance" in #conditions-precedent^seller-responsibility: §cp-competition-clearance} | {"cp-financing" in #conditions-precedent^seller-responsibility: §cp-financing} | {"cp-security-release" in #conditions-precedent^seller-responsibility: §cp-security-release} | {"cp-waiver-first-refusal" in #conditions-precedent^seller-responsibility: §cp-waiver-first-refusal}} as soon as [reasonably] possible.

2. <#Purchaser> shall use <its: purchaser> best efforts to satisfy or procure the satisfaction of #conditions-precedent in {AND | {"cp-change-of-control" in #conditions-precedent^!purchaser-responsibility: §cp-change-of-control} | {"cp-competition-clearance" in #conditions-precedent^purchaser-responsibility: §cp-competition-clearance} | {"cp-financing" in #conditions-precedent^purchaser-responsibility: §cp-financing} | {"cp-security-release" in #conditions-precedent^purchaser-responsibility: §cp-security-release} | {"cp-waiver-first-refusal" in #conditions-precedent^purchaser-responsibility: §cp-waiver-first-refusal}} as soon as [reasonably] possible.

3. Each @singular(#-parties) shall notify the other @singular(#-parties) as soon as it becomes aware that @singular(#?conditions-precedent) has been satisfied.

Using internal snippets, we can improve this grammar:

1. <#Seller> shall use <its: seller> best efforts to satisfy or procure the satisfaction of #conditions-precedent in @CPS-SELLER as soon as [reasonably] possible.

2. <#Purchaser> shall use <its: purchaser> best efforts to satisfy or procure the satisfaction of #conditions-precedent in @CPS-PURCHASER as soon as [reasonably] possible.

3. Each @singular(#-parties) shall notify the other @singular(#-parties) as soon as it becomes aware that @singular(#?conditions-precedent) has been satisfied.

CPS-SELLER = {AND | {"cp-change-of-control" in #conditions-precedent^!seller-responsibility: §cp-change-of-control} | {"cp-competition-clearance" in #conditions-precedent^seller-responsibility: §cp-competition-clearance} | {"cp-financing" in #conditions-precedent^seller-responsibility: §cp-financing} | {"cp-security-release" in #conditions-precedent^seller-responsibility: §cp-security-release} | {"cp-waiver-first-refusal" in #conditions-precedent^seller-responsibility: §cp-waiver-first-refusal}}

CPS-PURCHASER = {AND | {"cp-change-of-control" in #conditions-precedent^!purchaser-responsibility: §cp-change-of-control} | {"cp-competition-clearance" in #conditions-precedent^purchaser-responsibility: §cp-competition-clearance} | {"cp-financing" in #conditions-precedent^purchaser-responsibility: §cp-financing} | {"cp-security-release" in #conditions-precedent^purchaser-responsibility: §cp-security-release} | {"cp-waiver-first-refusal" in #conditions-precedent^purchaser-responsibility: §cp-waiver-first-refusal}}

Alternatively, using external snippets, we would have the following three clauses:

1. <#Seller> shall use <its: seller> best efforts to satisfy or procure the satisfaction of #conditions-precedent in @#cps-seller as soon as [reasonably] possible.

2. <#Purchaser> shall use <its: purchaser> best efforts to satisfy or procure the satisfaction of #conditions-precedent in @#cps-purchaser as soon as [reasonably] possible.

3. Each @singular(#-parties) shall notify the other @singular(#-parties) as soon as it becomes aware that @singular(#?conditions-precedent) has been satisfied.

A snippet called cps-seller:

{AND | {"cp-change-of-control" in #conditions-precedent^!seller-responsibility: §cp-change-of-control} | {"cp-competition-clearance" in #conditions-precedent^seller-responsibility: §cp-competition-clearance} | {"cp-financing" in #conditions-precedent^seller-responsibility: §cp-financing} | {"cp-security-release" in #conditions-precedent^seller-responsibility: §cp-security-release} | {"cp-waiver-first-refusal" in #conditions-precedent^seller-responsibility: §cp-waiver-first-refusal}}

And a snippet called cps-purchaser:

{AND | {"cp-change-of-control" in #conditions-precedent^!purchaser-responsibility: §cp-change-of-control} | {"cp-competition-clearance" in #conditions-precedent^purchaser-responsibility: §cp-competition-clearance} | {"cp-financing" in #conditions-precedent^purchaser-responsibility: §cp-financing} | {"cp-security-release" in #conditions-precedent^purchaser-responsibility: §cp-security-release} | {"cp-waiver-first-refusal" in #conditions-precedent^purchaser-responsibility: §cp-waiver-first-refusal}}

These final two external snippets can be used in other clauses as well by using the references @#cps-seller and @#cps-purchaser.

Using snippets to reuse values

While most snippets will contain text, it is also possible to use snippets as containers for data-values and calculations. For example:

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

@INTEREST = (100 + #contract^minimum-interest-base + (#contract^value * 0.05))

Instead of repeating the fairly complex interest-calculation all over the contract, you can store it in an (internal or external) snippet and reuse it.

Note: When storing a value or calculation in an external snippet, you should wrap it in curly braces { ... } to avoid that the contents of the snippet would be treated as clause text. (As explained in Mixing Data Types, clause text cannot be used to perform calculations.)

Using (internal) snippets to reuse conditions

Internal snippets cannot only store values and expressions, but also conditions. For example, instead of repeating the same logic over and over again:

1. {#contract^value > 6000 EUR AND #contract^jurisdiction = "dutch": For high-value contracts under Dutch law, #Seller shall provide the following exception ...}

2. If #Buyer purchases more than {#contract^value > 6000 EUR AND #contract^jurisdiction = "dutch": 300 | else: 600} items, then ...

…. you can store the condition in an internal snippet, and reuse it everywhere, thereby increasing readability and consistency:

1. {@HIGH-VALUE-DUTCH: For high-value contracts under Dutch law, #Seller shall provide the following exception ...}

2. If #Buyer purchases more than {@HIGH-VALUE-DUTCH: 300 | else: 600} items, then ...

HIGH-VALUE-DUTCH = #contract^value > 6000 EUR AND #contract^jurisdiction = "dutch"

Using snippets to perform if/then/else switches within another calculation

Sometimes it is useful to switch between values in the middle of a calculation.

For example, assume that in a certain contract the price of the tomatoes that are sold, depends on the country, the weather and the volume:

price = base-price * country-factor * weather-factor * volume

If, for example, there are 4 possible countries (NL / FR / DE / UK) and 3 possible weather-conditions (dry / humid / stormy), you would end up with a huge number of if/then/else parts:

The agreed price is equal to: 
{ #country^name = "nl" AND #weather^condition = "dry": #contract^base-price * 1.1 * 2.1 * #contract^volume
| #country^name = "nl" AND #weather^condition = "humid": #contract^base-price * 1.1 * 2.3 * #contract^volume
| #country^name = "nl" AND #weather^condition = "stormy": #contract^base-price * 1.1 * 2.5 * #contract^volume
| #country^name = "fr" AND #weather^condition = "dry": #contract^base-price * 1.5 * 2.1 * #contract^volume
| #country^name = "fr" AND #weather^condition = "humid": #contract^base-price * 1.5 * 2.3 * #contract^volume
| #country^name = "fr" AND #weather^condition = "stormy": #contract^base-price * 1.5 * 2.5 * #contract^volume
| and so on for the other two countries}

In such situations, it is much cleaner to use the following:

The agreed price is equal to: 
{ #contract^base-price * @COUNTRY * @WEATHER * #contract^volume }

COUNTRY = {#country^name = "nl": {1.1} | "fr": {1.5} | "de": {1.8} | "uk": {1.2}}

WEATHER = {#weather^condition = "dry": {2.1} | "humid": {2.3} | "stormy": {2.4}}

Snippets with parameters

Introduction

For even greater reuse of text blocks, you can optionally use placeholders in (internal or external) snippets.

For legal experts who are first confronted with this idea, this will seem like a far-fetched idea. However, its usefulness should quickly become clear with the use of some examples.

Assume that you have a datafield #employee^gender that can either contain "female" or "male" as a value. In your paragraphs, you want to alternate between “Mr.” and “Mrs.”, depending on the gender. This is of course very easy:

... and {#employee^gender = "female": Mrs. | else: Mr.} #employee^last-name shall be obliged to ...

Let’s make this a little bit more complex. Assume that you not only have #employee^gender, but also #manager^gender and #consultant^gender, and you also want to alternate between “Mr”. and “Mrs.” for these datafields:

... and {#employee^gender = "female": Mrs. | else: Mr.} #employee^last-name shall be obliged to do X, as supervised by {#manager^gender = "female": Mrs. | else: Mr.} #manager^last-name and assisted by {#consultant^gender = "female": Mrs. | else: Mr.} #consultant^last-name

This is still easy, but quickly becomes quite verbose, with a lot of repetition. The structure of the three conditions is actually identical, the only difference is the datafield that is being referenced.

Using a single placeholder

To avoid this repetitiveness, you can use placeholders within a snippet:

... and @MR-MRS(?GENDER := #employee^gender) #employee^last-name shall be obliged to do X, as supervised by @MR-MRS(?GENDER := #manager^gender) #manager^last-name and assisted by @MR-MRS(?GENDER := #consultant^gender) #consultant^last-name

MR-MRS = {?GENDER = "female": Mrs. | else: Mr.}

As you know by now, the software will replace each reference to @MR-MRS, by the contents of the snippet. If you also specify one or more placeholders between parentheses, then the software will additionally replace each placeholder with the specified content.

For example, @MR-MRS(?GENDER := #employee^gender) will be converted into {#employee^gender = "female": Mrs. | else: Mr.}, because the ?GENDER placeholder within the snippet is being replaced with the value #employee^gender.

As a result, you can use the very same snippet for three different datafields, by having the software swap the placeholder.

Using multiple placeholders

You can also use multiple placeholders for snippets. For example, let’s also include the last name in the snippet:

... and @MR-MRS(?GENDER := #employee^gender, ?NAME := #employee^last-name) shall be obliged to do X, as supervised by @MR-MRS(?GENDER := #manager^gender, ?NAME := #manager^last-name) and assisted by @MR-MRS(?GENDER := #consultant^gender, ?NAME := #consultant^last-name) 

MR-MRS = {?GENDER = "female": Mrs. | else: Mr.} ?NAME

In this short paragraph, this may not seem like a huge advantage. However, from a maintenance perspective — particularly when using external snippets — this is a significant improvement, because the way that a person’s title and name are being represented, can then be centrally organised. If ever you want to change the way persons are inserted in the documents (e.g., a new corporate policy would require to say “MR. SMITH” instead of “Mr. Smith”) then you only have to change one small piece of text, instead of having to “hunt” in many different files for potentially hundreds of instances.

Short-hand placeholders

To reduce the amount of text you have to insert, ClauseBase allows you to omit ?PLACEHOLDER :=

The example above can thus be shortened to:

... and @MR-MRS(#employee^gender, #employee^last-name) shall be obliged to do X, as supervised by @MR-MRS(#manager^gender, #manager^last-name) and assisted by @MR-MRS(#consultant^gender, #consultant^last-name) 

MR-MRS = {?A = "female": Mrs. | else: Mr.} ?B

When no explicitly named placeholders are being used, ClauseBase will assume that your placeholders are being named ?A, ?B, ?C, … corresponding to the first, second, third, … parameter in the invocation of the snippet.