Special functions

Contents

Usage tips

  • Don’t forget that each of the special functions below can be combined with other special functions, through AND / OR.
  • Every special function that returns true/false can be “inverted” by wrapping it in a NOT. For example, not(@assigned(#concept^datafield)) will return true if that datafield is not assigned a value.
  • When you are typing in the name of a function in the editor, you can get a list of matching functions by pressing Control + Spacebar after you have inserted the @-symbol and at least a few letters:
  • When you want to get a summary of the function’s purpose and its arguments, you can press the same shortcut Control + Spacebar when your cursor is between the parentheses of that function:

Overview per type

Calculations@construct-currency @count @difference @intersection @length @lookup @nth @percent-divide
Concepts@implemented @implemented-all @implemented-any

@ref-if

@has-definition @has-autonomous-definition @has-integrated-definition @definitionlist-present
Conditions@cascade @cycle @if @switch @when

@implemented @implemented-all @implemented-any

@in-browser @in-pdf @in-docx

@lookup

@one-else @one-else-nr

@ref-if

@shrink-level

@crosstag-implemented [deprecated]

@silence
Datafields@assigned
Dates  & durations@calendar-days

@construct-date @construct-duration

@days-in-month @days-in @months-in @quarters-in @weeks-in @years-in @duration-unit

@duration-apostrophe

@earliest @latest

@format-date

@fullmonth

@is-days @is-months @is-quarters @is-weeks @is-years

@is-valid-date

@first-day-of-month @last-day-of-month

@days-between @months-between @weeks-between

@day-of @month-of @year-of

@minutes-in-timings @minutes-in-timing-lists @minutes-to-timing

@today

@week-nr @weekday-nr @weekday
Languages & conjugations@arabic @bulgarian @chinese @czech @danish @dutch @english @estonian @finnish @french @german @greek @hungarian @italian @latvian @lithuanian @norwegian @polish @portuguese @romanian @russian @slovak @slovenian @swedish @turkish

@is-plural @is-singular  @is-male @is-female @is-neutral @male-female

@in-language @multi-language

@a-or-an @acc @case @art-def @art-undef

@one-else @one-else-nr

@possessive @plural @singular @singular-plural
Lists@count @empty-list @sum

@difference @intersection @union @is-subset

@bullets @enumerate @numbered-paragraphs

@distinct @filter @filter-indices @filter-by-indices @is-duplicate

@for

@list-if-all

@get @nth

@sort
Numbers@average @count @dynamic-fullnr @fullnr @fullcurrency @fullduration

@extract-currency @extract-number

@abs @floor

@format-plain-nr @format-nr @ord @short-ord

@min @max

@marginal @pagecount @pagenr @seq @tracked-seq @tracked-seq-list

@percent-divide

@range

@round
References@bookmark @bookmark-link @bookmark-pagelink

@clause-title @doctitle @ref-if @ref-title

@refs-and @refs-or @refs-if-and @refs-if-or

@last-level @long-ref @short-ref @drop-doc-ref @remove-this

@ref-subclauses @ref-siblings-before @ref-siblings-after
Repeating (looping)@index
Special items@black-hole @comment @email @image @link @lorem @merge-tables @open-qa @pagecount @pagenr @para @paras @placeholder @reporting @tab @void

@msword-pages @msword-pages-own-nrs @msword-fragment

@insert-document

@checkbox @currencybox @datebox @listbox @nrbox @textbox

@cc-checkbox @cc-combobox @cc-currencybox @cc-datebox @cc-listbox @cc-textbox @cc-plaintextbox @cc-multiline-textbox
Text structure@asterisks @bullets @enumerate @for @str @in-binder @pagecount @text-part  @toc @toc-o1 @terms-toc @underscores
Text modification@format-plain-nr @format-nr

@comma-split @regex-split @semicolon-split @space-split @to-paragraphs

@endnote @footnote

@lowercase @uppercase @capitalize @capitalize-words @uncapitalize

@trim

@sub @lsub @rsub

@length @matches @strictly-matches

@regex-find @regex-find-all @regex-replace
User@user-first-name @user-last-name @user-tags
Q&AOnly valid within a Q&A: @answer @column @card-enabled @question-enabled @row-index @shared-condition

@answer

This special function can only be used within Q&A expression conditions.

@assigned

Returns true if some value is assigned to the datafield (i.e., if the datafield is not equal to unassigned).

Tip: you can easily invert the behaviour of this special function: not(@assigned(#concept^datafield)) will return true if the datafield is not assigned any value.

In visual terms, the @assigned function actually boils down to the question whether the data dashboard shows the left side (= no value assigned) or the right side.

date and delivery-location are not assigned any value
date is assigned a value (so that @assigned(#order^date) would return true), while delivery-location is still not assigned a value

The @assigned function may cause quite some surprises for new users.

Be aware that assigning an empty text value to a text datafield (visually shown in the data dashboard as an empty text box) causes the @assigned function to return true for that datafield.

Similar surprises will happen with:
* assigning the value false to a true/false datafield (visually represented as a checkbox that is not checked)
* assigning the value 0 to a number datafield
* assigning a collection of no items to a list of text or repeating datafield — which will already happen in a Q&A when a question has been associated with this datafield

because all of these situation cause the @assigned function to return true for that datafield, because “something” is assigned (yes, even an empty collection is “something”). This will probably come as a surprise if you are new to thinking in data types.

Tip: to check whether at least one item is assigned to a list of text or repeating datafield, you can use @count(#concept^datafield) > 0

@a-or-an

  • parameter: some text (a word)
  • returns: that word, preceded by either “a” or “an”

This function inserts the undefined article “a” or “an” before an English word. For example, when passing “house” it will return “a house”, while if passing “animal” it will return “an animal”.

Please note that, while this special function uses a reasonably advanced algorithm and takes into account many different exceptions, there exists no exhaustive list of words and their undefined article, so in a few edge-cases errors may occur.

@abs

  • parameter: a number or currency
  • returns: the absolute value of that number or currency

For example, @abs(-5 EUR) will return 5 EUR, while @abs(-789) will return 789 and @abs(123.45) will return 123.45.

@acc

  • any type of parameter
  • returns: that same parameter, but flagged as requesting the accusative case
  • see also: @case

This function causes its parameter to be flagged as requiring the accusative case. Currently, the only scenario where this is supported, is for durations in Lithuanian. (Please contact us if you would have your own use cases).

This function has no effect in languages that do not support cases (such as English, French and Dutch).

@arabic

For example, @arabic — no parameters or parentheses necessary — would return true if the currently active language is Arabic, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@arabic) will return true if any other language but Arabic is active.

@art-def

  • parameter: a concept
  • returns either nothing (if no defined articles apply in the language) or text representing the correct defined article

For example, in French, @art-def(#buyer) would return l' if the conceptlabel would be set to “acheteur”.

This special function can be useful for situations where you need to split the article from the concept — as would for example be the case when you want the defined term to be bold, but not its article. For languages such as English (where the defined article is always the same), you can simply write something like the ~#-employer~ . In German, however, the article will change depending on the gender and grammatical function of the noun (concept), so you do not necessarily know which article will apply. In such cases, @art-def is crucial, as it allows you to write @art-def(#employer) ~#-employer~ .

Tip: you can force a certain grammatical case by combining @art-def with @case. In the previous example, you could for example write @art-def(@case(#employer, "g")) ~#-@case(employer, "g")~ to force both the article and the conceptlabel into genitive.

@art-undef

  • parameter: a concept
  • returns either nothing (if no undefined articles apply in the language) or text representing the correct undefined article

For example, in French, @art-undef(#buyer) would return un if the conceptlabel would be set to “acheteur”.

This special function operates in exactly the same way as @art-def, except that it returns an undefined article.

@asterisks

  • single parameter: the number of asterisks to insert

Inserts a centered paragraph that contains the specified number of asterisks, separated by 10 spaces. The paragraph contains 25pt spacing above.

This special function’s typical use case is before a signatures block — example:

@average

  • parameters: a list of numbers or currency values
  • returns: the average of those numbers/values

This function returns the average of the list of values. For example:

  • @average(@list(2, 4, 6)) returns 4
  • @average(@list(2.1, 3.2, 4.4)) returns 3.233
  • @average(@list(2100 EUR, 3200 EUR, 4405 EUR)) returns 3235 EUR

Before performing the calculation, all non-number values are removed from the list. You can mix freely floating-point numbers with whole numbers. However, if you specify any currency value, then all currency values must have the currency value (e.g., EUR).

@black-hole

  • parameters: any amount, of any type (they will get ignored)
  • returns: nothing
  • see also: @void

This special function is similar to @void, in the sense that it does not return a visual result, but can be used as a placeholder in situations where the grammar technically requires you to include something.

The difference with @void is that @black-hole takes one or more arguments, and pretends it actually uses them (even though it actually ignores them). Accordingly, any datafield that you would pass as a parameter, will be flagged as being used, so will be shown in the data dashboard, and (when accompanied by !) may invite the user to specify a value, even if that value will not be used at that point.

For example, in the screenshot below, you can see that the employee’s address gets requested at the beginning of the document (through the purple box) but not within the table. (See the explanation about the advanced use of the! within the datafield).

When some address is filled in, the result will be that the address is only visible within the table. Note that in both scenarios, the data dashboard would show the datafield as effectively being used.)

@bookmark

  • first parameter: the name of the bookmark (which — according to MS Word’s specifications — should not contain any spaces or punctuation, and must not start with a number)
  • second parameter: any parameter that can be converted into text. Note that bookmarks are not intended to cover multiple paragraphs.
  • see also: @bookmark-link

This function inserts an MS Word “bookmark” around the text specified in the parameter. Afterwards, you can then establish a clickable hyperlink to this area of text through the @bookmark-link function.

As suggested by the name, “bookmarks” act as reference locations inside MS Word, spanning the text you specified as the first parameter. Once inserted at some location in the document, you can then elsewhere refer to them, either with the text of the bookmark, or with the number of the paragraph in which the bookmark is located. Note that bookmarks leave no visual traces within the document: you can only detect their presence by showing the “Insert Cross-References” dialog box and asking for the list of bookmarks.

For example, @bookmark("alpha", "some random text") will insert the plain text “some random text” in the document, and attach a bookmark named “alpha” to that piece of text.

If you want to insert more rich text as the second parameter, you are advised to refer to an internal snippet. For example, @bookmark("alpha", @BETA) will insert whatever text is associated with internal snippet BETA into the document, and associate a bookmark called “alpha” to it.

This function inserts a (clickable) hyperlink to the specified bookmark. The text that will get inserted is equal to the text covered by the targeted bookmark.

For example, when you would use @bookmark("alpha", "some text beta") in some clause, you can refer to that text elsewhere with @bookmark-link("alpha"). The latter special function call will result in the text “some text beta” being inserted in the document, as a clickable hyperlink.

This function inserts a (clickable) hyperlink to the specified bookmark. The text that will get inserted is equal to the page number the targeted bookmark.

For example, when you would use @bookmark("alpha", "some text beta") in some clause, you can refer to that text elsewhere with @bookmark-pagelink("alpha"). The latter special function call will result in the number of the page (e.g., 34) being inserted in the document, as a clickable hyperlink.

@bulgarian

For example, @bulgarian — no parameters or parentheses necessary — would return true if the currently active language is Bulgarian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@bulgarian) will return true if any other language but Bulgarian is active.

@bullets

(including @bullets-and / @bullets-or / @bullets-andor / @bullets-skipfinal / @bullets-and-skipfinal / @bullets-or-skipfinal / @bullets-andor-skipfinal)

  • parameters: either a list, or one or more values (which may themselves be lists, from which the elements will then be extracted)
  • returns a bulleted list if at least one item results in output (no result if an empty list or item without output is passed)
  • see also: @enumerate

Converts the parameter(s) into an enumeration that will always be displayed as a bullet-set.

For example:

  • inserting @bullets(‘alpha’, ‘beta’, ‘gamma’) is identical to typing {LIST! | alpha | beta | gamma}
  • inserting @bullets-and(‘alpha’, ‘beta’, ‘gamma’) is identical to typing {AND! | alpha | beta | gamma}

Use @enumerate instead if you do not necessarily want to force the use of bullets, but instead want to rely on the applicable styling to determine how an enumeration should be shown.

The functions that include ….-skipfinal can be used if you want to avoid that the final item receives a suffix.For example, @bullets(‘alpha’, ‘beta’, gamma’) results in a list of three bullets, for which the last bullet (containing “gamma”) will probably end at the suffix “.” (or any other suffix that happens to be selected in the layout settings). To prevent such suffix from being inserted, used @bullets-skipfinal.

@calendar-days

  • parameter: either a duration or a number
  • returns text

Returns a piece of text saying “… calendar days”, in the current language and (if specified in the styling) with … being a number and/or words between parentheses. If the duration would happen to be currently specified in another time-unit than days, then a conversion to days will occur (similar to a using @days-in).

For example, if the styling for English specifies to use both numbers and words between parentheses, @calendar-days(5) will return “five (5) calendar days”, while @calendar-days(1) will return “one (1) calendar day” (notice the singular word “day”).

@capitalize

Returns the passed text, but with its first letter converted to a capital.

For example, @capitalize(‘just testing’) results in Just testing.

@capitalize-words

Returns the passed text, but with every individual word receiving an initial capital.

For example, @capitalize-words(‘just testing some words’) results in ‘Just Testing Some Words’.

@card-enabled

This special function can only be used within Q&A expression conditions.

@cascade

  • one or more parameters of any type
  • can return any type
  • see also: @assigned

Returns the first parameter that is not equal to nothing.

For example, @cascade(#employee^last-name, #employee^first-name) would result in the value assigned to #employee^last-name if that datafield was effectively assigned some value. If no value is assigned to #employee^last-name, then the value assigned to #employee^first-name would be returned. If no value would be assigned to that datafield either, then the result would be nothing.

@case

  • parameters:
    • a concept or reference
    • text, with the first letter(s) of the required grammatical case
  • returns the parameter (e.g., if a concept was specified, it will return a concept) with the grammatical case applied to it

For example, @case(#buyer, "g") will return the specified concept, forced into the genitive. Read more about the use of grammatical cases on the Conjugations page.

@cc-checkbox

  • parameters:
    • checked? (true/false)
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates an MS Word Content Control checkbox form field that is checked or unchecked
  • see also: @checkbox

This function creates a Content Control checkbox in MS Word (optionally containing the specified internal name, which will show up as a hint towards the end-user in Microsoft Word).

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: You may also want to check out @checkbox, for the traditional (legacy) version of a checkbox form field. See the discussion on the new approach to form controls of MS Word.

@cc-combobox

  • parameters:
    • list of texts (or list-of-text datafield)
    • optional index or text of the selected text item
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates a” Content Control” MS Word dropdown form field containing the specified text items
  • see also @listbox and @cc-listbox

This function creates a “Content Control” dropdown list form field in MS Word that contains the specified text items. Note that, unlike @listbox and @cc-listbox, Microsoft Word will allow the end-user to choose his/her own text item, in addition to the predefined text-items in the dropdown list.

When the (optional) second parameter is not passed, the first item will be selected in MS Word; if you want to have some other item preselected, you can either pass the (one-based) index of the item to select, or the text of the item you want to select. Optionally you can also pass a third parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

For example, both @cc-combobox(@list("alpha", "beta", "gamma"), "beta") and @listbox(@list("alpha", "beta", "gamma"), 2) create a dropdown-list in MS Word, with the second item (beta) being selected.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: While there are probably limited reasons to do so, you may instead want to choose the traditional (legacy) form control @listbox instead of the “Content Control” new approach to form controls of MS Word.

@cc-datebox

  • parameters:
    • optional date datafield (or date value)
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates a “Content Control” MS Word form field containing the optionally specified parameter
  • see also: @cc-datebox

This function creates a “Content Control” box in MS Word that optionally contains the specified date value (it will be empty when no parameters are passed). Optionally you can also pass a second parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

Unlike @datebox, Microsoft Word will present a nice calendar dropdown box that will allow end-users to easily choose the desired date. Furthermore, when a new date is selected by the end-user, it will be automatically formatted in accordance with the (short date) styling preferences. @cc-datebox will therefore most likely be preferred over @datebox.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: You may instead want to choose the traditional (legacy) form control inserted through @datebox, instead of the “Content Control” new approach to form controls of MS Word.

@cc-listbox

  • parameters:
    • list of texts (or list-of-text datafield)
    • optional index or text of the selected text item
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates a” Content Control” MS Word dropdown form field containing the specified text items
  • see also @listbox and @cc-combobox

This function creates a “Content Control” dropdown list form field in MS Word that contains the specified text items. Note that, unlike @cc-combobox, the end-user can only choose the predefined text-items from the dropdown list in MS Word. Accordingly, Microsoft Word will not allow the end-user to choose his/her own text item instead of the predefined text-items in the dropdown list.

When the (optional) second parameter is not passed, the first item will be selected in MS Word; if you want to have some other item preselected, you can either pass the (one-based) index of the item to select, or the text of the item you want to select. Optionally you can also pass a third parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

For example, both @cc-listbox(@list("alpha", "beta", "gamma"), "beta") and @listbox(@list("alpha", "beta", "gamma"), 2) create a dropdown-list in MS Word, with the second item (beta) being selected.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: While there are probably limited reasons to do so, you may instead want to choose the traditional (legacy) form control @listbox instead of the “Content Control” new approach to form controls of MS Word.

@cc-multiline-textbox

  • parameters:
    • optional text datafield (or text value)
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates a “Content Control” MS Word form field containing the optional textbox, which can potentially span across multiple lines
  • see also @textbox, @cc-textbox, @cc-plaintextbox

This function creates a box in MS Word that optionally contains the specified text value (it will be empty when no parameters are passed). Optionally you can also pass a second parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

Note that unlike @cc-textbox and @cc-plaintextbox, this textbox can contain multiple paragraphs as content. Accordingly, please be aware that this box is treated by ClauseBase as a separate paragraph in the final output in MS Word — i.e., you will almost always want to put the call to @cc-multiline-textbox in its own separate paragraph

Unlike @cc-plaintextbox, the end-user can freely format the text inside the textbox with bold, italic, etc.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: You may instead want to choose the traditional (legacy) form control inserted through @textbox, instead of the “Content Control” new approach to form controls of MS Word.

@cc-plaintextbox

  • parameters:
    • optional text datafield (or text value)
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates a “Content Control” MS Word form field containing the optional textbox
  • see also @textbox, @cc-textbox and @cc-multiline-textbox

This function creates a “Content Control” box in MS Word that optionally contains the specified text value (it will be empty when no parameters are passed). Optionally you can also pass a second parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

Unlike @cc-textbox and @textbox, the end-user cannot freely format the text inside this box — the formatting can be changed, but any formatting change will uniformly apply to all characters in the box.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: You may instead want to choose the traditional (legacy) form control inserted through @textbox, instead of the “Content Control” new approach to form controls of MS Word.

@cc-textbox

  • parameters:
    • optional text datafield (or text value)
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates a “Content Control” MS Word form field containing the optional textbox
  • see also @textbox, @cc-multiline-textbox and @cc-plaintextbox

This function creates a “Content Control” box in MS Word that optionally contains the specified text value (it will be empty when no parameters are passed). Optionally you can also pass a second parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

Note that unlike @cc-multiline-textbox, this textbox cannot contain paragraphs as content. Unlike @cc-plaintextbox, the end-user can freely format the text inside the textbox with bold, italic, etc.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: You may instead want to choose the traditional (legacy) form control inserted through @textbox, instead of the “Content Control” new approach to form controls of MS Word.

@checkbox

  • parameters:
    • checked? (true/false)
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates an MS Word checkbox form field that is checked or unchecked
  • see also: @cc-checkbox

This function creates a checkbox in MS Word (optionally containing the specified internal name, which will show up in the form field’s options inside MS Word).

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: You may also want to check out @cc-checkbox, for the “Content Control” version of a checkbox, which uses the new approach to form controls of MS Word.

@chinese

For example, @chinese — no parameters or parentheses necessary — would return true if the currently active language is Chinese, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@chinese) will return true if any other language but Chinese is active.

@clause-title

  • parameter: a #concept or a §cross-tag
  • returns the title of the clause that implements the concept/cross-tag (or empty text if the concept is not implemented, or is implemented but the implementing clause has no title)
  • see also: @ref-title

Returns, as a text value, the title of the first clause that implements the concept/cross-tag.

For example @clause-title(#liability) could result in Liability limitations agreed between the Parties.

@column

This special function can only be used within Q&A expression conditions.

@comment

  • first parameter: either text, or an internal snippet

This function inserts a comment (balloon) in the DOCX/PDF output; it has no visible effect within the browser.

For example, @comment("Some random comment") would create a comment balloon that contains the plain text “Some random comment”.

When you require more rich content, you should create an internal snippet and refer to that snippet as the first parameter. For example:

will result in the following comment balloon inside MS Word:

Note that, when combined with various conditions, this function allows you to dynamically show/hide comments and alter the contents. This can have interesting use cases.

Also note that the output of this function is not affected by the document or Q&A’s settings related to the export of comments & notes. If you do not want the comment to be exported in certain circumstances, you should subject the function to a condition.

@comma-split

For example, @comma-split("alpha, beta, gamma") would result in a list with three elements (“alpha”, “beta” and “gamma”). Please note that the spaces around the commas are removed.

@construct-duration

  • first parameter: an amount (e.g., 5)
  • second parameter: “year”, “month”, “day”, “week” or “quarter” (or any of them in plural)

Returns a duration value that consists of the specified amount and unit.

Example: @construct-duration(5, "days")

@construct-currency

  • first parameter: an amount (e.g., 500 or 5.123)
  • second parameter: “USD”, “EUR”, “GBP” or “JPY”
  • see also: @extract-currency

Returns a currency value that consists of the specified value and currency.

For example, {@construct-currency(500, "EUR") + 1 EUR} is equal to having typed {500 EUR + 1 EUR}

@construct-date

  • first parameter: the year (e.g., 2020)
  • second parameter: the month (e.g. 11 for November)
  • third parameter: the day (e.g., 23)
  • returns a date value constructed of the passed parametesr

For example, @construct-date(2020, 12, 23) will return the date of 23rd December 2020.

@count

  • parameter: some list
  • returns a whole number
  • see also: @list and @length (for calculating the length of text)

Returns the number of elements present in the list. 

For example, @count(@empty-list) results in 0, while @count(@list(‘alpha’, ‘beta’)) results in 2.

@crosstag-implemented

  • please do not use anymore — use @implemented instead
  • parameter: a string

Returns true when some clause that is currently visible in the document implements the specified tag.

@currencybox

  • optional parameters:
    • currency datafield (or currency value)
    • the number of decimal places (digits after the comma/period)to enforce upon numbers inserted by the end-user in the .DOCX file
    • the currency to enforce upon numbers inserted by the end-user in the .DOCX file
    • name (text) — this is an advanced parameter that you can probably ignore
  • creates an MS Word form containing the optionally specified parameter
  • see also: @cc-currencybox, @checkbox, @datebox, @listbox, @nrbox and @textbox

This function creates a box in MS Word that optionally contains the specified currency value (it will be empty when no parameters are passed).

Optionally you can also specify the number of decimal places and the currency to enforce when the end-user inserts a number in the .DOCX file. When these parameters are not explicitly passed:

  • For the decimal places, the corresponding values of the currently applicable styling will be used (for which the platform’s default is 4 decimal places). Note that MS Word only allows a fixed number of decimal places, and does not allow dropping unnecessary zeroes (e.g., if 2 decimal places would be used, then a value such as 6 EUR will get formatted as 6,00 EUR in metric style, or 6.00 in imperial style).
  • For the currency, the platform’s default currency will be used (e.g., euros in the Belgian and French jurisdictions, British Pounds in the UK jurisdiction, and US Dollars in the US jurisdiction).

A final optional parameter contains the specified internal name, which will then show up in the form field’s options inside MS Word.

Examples:

  • @currencybox(5 EUR) will insert a box that contains the value “5 EUR”. When the end-user would insert a new value into that box, it will get formatted with the number of digital places indicated by the platform (probably 4) and the platform’s default currency (e.g., EUR on a server for the French jurisdiction; depending on the styling setting, it may also become the Euro-symbol and get printed before/after the number).
  • @currencybox(5.02 GBP, 2, "GBP") will insert a box with value “5.02 EUR”. When the end-user would insert a new value into that box (e.g. the number 6), it will get formatted with 2 decimal places and currency GBP — so for example 6.00 GBP or £6.00, depending on the applicable styling settings.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: You may also want to check out @cc-currencybox, for the “Content Control” version, which uses the new approach to form controls of MS Word.

@czech

  • no parameters
  • returns true or false

For example, @czech — no parameters or parentheses necessary — would return true if the currently active language is Czech, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@czech) will return true if any other language but Czech is active.

@cycle

  • parameters:
    • a datafield
    • a concatenation of test-values and result-values
  • runs through the test-values and returns the first result-value for which the test-value is equal to the value of the datafield
  • see also: @if, @switch and @when

For example, @case(#employee^first-name, "Charlie", "Brown", "Bart", "Simpson") will return “Simpson” if the current value of the employee’s first name happens to be “Bart”.

@danish

  • no parameters
  • returns true or false

For example, @danish — no parameters or parentheses necessary — would return true if the currently active language is Danish, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@danish) will return true if any other language but Danish is active.

@datebox

  • parameters:
    • optional date datafield (or date value)
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates an MS Word form field containing the optionally specified parameter
  • see also: @cc-datebox

This function creates a box in MS Word that optionally contains the specified date value (it will be empty when no parameters are passed). Optionally you can also pass a second parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

Note that what actually gets inserted, is a simple text box in which the user can specify a date. However, whatever the user is inserting, is not validated or reformatted by MS Word. You may therefore want to check out @cc-datebox instead, which uses the new approach to form controls of MS Word.

When using @cc-datebox, instead of @datebox, Microsoft Word will present a nice calendar dropdown box that will allow end-users to easily choose the desired date. Furthermore, when a new date is selected by the end-user, it will be automatically formatted in accordance with the (short date) styling preferences. @cc-datebox will therefore most likely be preferred.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

@day-of

  • parameter: a date
  • returns a whole number between 1 – 31
  • see also: @month-of and @year-of

Returns the day number (1 – 31) for the specified date.

@days-in

Returns the number of days in the duration value.

Note that rounding errors can occur, because averages will be used, and no specific dates, leap years, etc. will be taken into account! For example, @days-in(1 month) will result in 30.

@days-in-month

  • parameter: a date
  • returns a whole number

Returns the date of the last day of the month in the specified date.

For example, @days-in-month(2020_2_1) returns 29, because February has 29 days in the leap year 2020.

@days-between

Returns the number of full days between the two dates.

Examples:

  • @days-between(2019_2_5, 2019_2_6) will result in 1
  • @days-between(2019_2_5, 2019_3_5) will result in 28
  • @days-between(2019_2_5, 2019_8_23) will result in 199

@definitionlist-present

Returns true if at least one definition-list is present in the document. This function, together with @has-definition, allows you check whether some defined term has a definition attached to it.

Note that this function will also return true when the only definition list that is currently present, happens to be a non-exhaustive definition list in which only certain terms are currently visible.

@difference

  • parameters: two lists (the second parameter will be automatically converted to a list)
  • returns a list
  • see also: @intersection and @union

Returns the difference between the two lists, i.e. it takes the first list, removes all the elements of the second list that are also present in the first list, and then returns the result.

Examples:

  • @difference(@list(1, 2, 3), @list(1)) results in a list with elements 2 and 3
  • @difference(@list(1, 2, 3), 1) results in a list with elements 2 and 3 — note that the second parameter was automatically converted to @list(1)
  • @difference(@list(1, 2, 3), @list(1, 2, 3)) results in an empty list, because both lists share the same elements
  • @difference(@list(1, 2, 3), @list(1, 1, 2, 2, 3)) also results in an empty list
  • @difference(@list(1, 1, 2, 2, 3, 3), @list(1, 2, 3)) also results in an empty list
  • @difference(@list(1, 1, 2, 2, 3, 3), @list(1, 2)) results in a list with elements 3 and 3

@distinct

  • single parameter is a list of elements
  • returns a list in which all the duplicate elements are removed
  • see also: @is-duplicate

For example, @distinct(@list(1, 2, 3, 3, 4, 4, 4, 5)) will return @list(1, 2, 3, 4, 5), while @distinct(@list("alpha", "gamma", "beta", "beta")) will return @list("alpha", "gamma", "beta").

@doctitle

  • no parameters
  • returns text

For example, @doctitle — no parameters or parentheses necessary — would insert the title of the current document. (When called insider a binder, the title of the document that contains the function-call will be returned.)

@drop-doc-ref

  • single parameter: a reference (e.g. §#concept or §tag)
  • returns the specified parameter, flagged with a preference for never showing the document’s title
  • see also @short-ref, @long-ref and @last-level

When referencing a clause outside of the current subdocument, ClauseBase will append the other subdocument’s title (e.g., “article 3.2 of Schedule 2”. Usually this is exactly what you want, but there are situations where you want to avoid this.

When wrapping a reference in @drop-doc-ref, the software will drop the reference to the subdocument’s title, when a clause is actually part of a Binder. (Outside of a Binder, this special function has no effect.)

@duration-apostrophe

  • single parameter: a duration
  • returns the duration, as text, with an apostrophe and -s where necessary

Converts the specified duration into the possessive word-version, adding an apostrophe and -s where necessary in English. For example, @duration-apostrophe(1 month) is converted into 1 month's, while @duration-apostrophe(2 years) is converted into 2 years'.

In any other language besides English, the duration is simply expanded into words, without any apostrophe or -s added.

@duration-unit

  • single parameter: a duration
  • returns the time-unit of the duration — either “year”, “month”, “day”, “week” or “quarter”.

For example @duration-unit(23 years) will return “year”, while @duration-unit(1 month) will return “month”.

This function can be very useful to differentiate between different types of durations that may have been entered by the end-user. For example, in a Q&A, combined with expression conditions, you could show certain questions only when a previous duration-related question was answered in weeks.

@dutch

For example, @dutch — no parameters or parentheses necessary — would return true if the currently active language is Dutch, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@dutch) will return true if any other language but Dutch is active.

@dynamic-fullnr

  • parameter: some whole number
  • returns text
  • see also: @fullnr

Returns the specified number either as-is (e.g., “30”), or in letters (e.g., “thirty”), or in letters with parenthesized numbers (e.g., “30 (thirty”)), depending on the styling settings.

@earliest

  • parameter: two dates
  • returns: a date
  • see also: @latest

Returns the earliest of the two dates.

For example, @earliest(2018_01_05, 2010_01_01) returns 1st January 2010.

@email

  • parameter: an email address (between quotes)
  • optional second parameter with visible text (if missing, the email address will be printed)
  • returns: a hyperlinked email address
  • see also: @link

For example @email("info@clausebase.com") returns a clickable link to an email address info@clausebase.com, while @email("info@clausebase.com", "please email us") returns a clickable link to the same email address, but visibly the text “please email us” will be shown.

@empty-list

  • no parameters
  • returns a list
  • see also: @list

For example, @empty-list — no parameters or parentheses necessary — returns a list with no elements.

@endnote

  • single parameter referring to an (internal or external) snippet
  • inserts an endnote
  • see also @footnote

Inserts an endnote, i.e. a footnote at the very end of a document. (This functionality is not frequently used in legal documents; typically it is used by book authors to insert notes at the end of a book or a book’s chapter).

@english

For example, @english — no parameters or parentheses necessary — would return true if the currently active language is English, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@english) will return true if any other language but English is active.

@enumerate

(Including @enumerate-and / @enumerate-or / @enumerate-andor / @enumerate-numbered / @enumerate-numbered-and / @enumerate-numbered-or / @enumerate-numbered-andor. All of them also include an alternative version with suffix -skipfinal, that skips the suffix for the final item.)

  • parameters: either a list, or one or more values (which may themselves be lists, from which the elements will then be extracted)
  • returns an enumerated list (or nothing, if the list is empty)
  • see also: @bullets

Converts the parameter into an enumeration, as if {AND | … | … } was typed in. Depending on the applicable styling, such enumeration may get displayed in an “inline” list, or instead as a bulleted list.

For example:

  • inserting @enumerate(‘alpha’, ‘beta’, ‘gamma’) is identical to typing {LIST | alpha | beta | gamma}
  • inserting @enumerate-or(‘alpha’, ‘beta’, ‘gamma’) is identical to typing {OR | alpha | beta | gamma}

The function versions that include -…numbered…- in their name, will be forced to show numbers when formatted as an inline list. For example, @enumerate(‘alpha’, ‘beta’, ‘gamma’) can — depending on the layout settings — result in “alpha, beta and gamma”. If instead you use @enumerate-numbered(‘alpha’, ‘beta’, ‘gamma’), then numbers will be inserted in between — in many layout settings this will for example look like “(i) alpha, (ii) beta and (iii) gamma”. This is similar to typing {AND | 1. alpha | 2. beta | 3. gamma}.If, in accordance with the layout settings, the @enumerate-numbered-… happens to result in a bulleted list, then the …-numbered-… part would make no difference.

@estonian

  • no parameters
  • returns true or false

For example, @estonian — no parameters or parentheses necessary — would return true if the currently active language is Estonian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@estonian) will return true if any other language but Estonian is active.

@extract-currency

Extracts the currency from the currency-value.

For example, @extract-currency(5 EUR) would extract the value “EUR”.

@extract-number

Extracts the amount from the currency-value.

For example, @extract-number(5 EUR) would extract the value 5.

@finnish

  • no parameters
  • returns true or false

For example, @finnish — no parameters or parentheses necessary — would return true if the currently active language is Finnish, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@finnish) will return true if any other language but Finnish is active.

@filter

  • parameters:
    • a list
    • a filtering expression, using @x as a placeholder for the actual element
  • results in the filtered list
  • see also @filter-indices

The specified list will be filtered using the expression contained in the second parameter. For example, @filter(@list(1, 2, 3, 4), @x < 3) will result in @list(1, 2) because each element is checked for being smaller than 3.

The expression can be as complex as you want, and can operate on different data types. For example, @filter(@list("alpha", "beta", "gamma"), not(@x = "gamma") or @x = "delta") will result in @list("alpha", "beta").

@filter-indices

  • parameters:
    • a list
    • a filtering expression, using @x as a placeholder for the actual element
  • results in a list containing the (one-based) indices of the elements that passed the test
  • see also @filter and @filter-by-indices

This function works similar to @filter, but will result in a list of indices (one-based) of those elements that passed the test.

For example, @filter-indices(@list(1, 2, 3, 4), (@x < 4) and (@x > 1)) will result in @list(2, 3).

@filter-by-indices

  • parameters:
    • a list
    • another list that contains the (one-based) indices of those elements that need to be kept in the first list
  • results in a filtered list
  • see also @filter and @filter-indices

This function filters the first list, and removes all elements for which the associated (one-based) index is not contained in the second list.

For example, @filter-by-indices(@list("alpha", "beta", "gamma"), @list(1, 3)) will result in @list("alpha", "gamma").

@first-day-of-month

Returns the date of the first day of the month in the specified date.

For example, @first-day-of-month(2019_02_05) returns 1st February 2019.

@floor

  • parameter: a (whole or fractional) number
  • returns: a whole number
  • see also: @round

Rounds the given number to the lowest integer — i.e., the decimal numbers are simply cut off. This function is typically used to avoid the rounding (to the nearest number) that will occur with automatic conversions.

Examples:

  • @floor(123.6) will result in 123
  • @floor(45) will result in 45
  • {100 / 6.0} will result in 16.6667, while {@floor(100 / 6.0)} will result in 16

@footnote

  • single parameter referring to an (internal or external) snippet
  • inserts a footnote in the document
  • see also @endnote

Inserts a footnote in the document, i.e. a piece of text at the bottom of a page. ClauseBase will print a small green “note” in the body of the text, to indicate that a footnote will be inserted at that location.

For example, the special certificate @footnote(@CERT), accompanied by an internal snippet CERT = obtained through a special procedure would insert the footnote “obtained through a special procedure” at the bottom of the page, while in the body of the page a superscript number (e.g., 1 or 2) gets inserted.

@for and @for-calc

  • parameters:
    • a placeholder
    • a list of elements (e.g., @list, list of texts datafield, or a repeating datafield)
    • a snippet that can optionally contain the specified placeholder, as well as the implicitly present placeholders ?INDEX and ?MAX-INDEX
  • results in a list of snippets (@for) or values (@for-calc)

This function results in a list of snippets or values, equal to the number of elements specified in the second parameter. At each iteration, the snippet will be changed so that the specified placeholder will be replaced by element of the current iteration. In addition, the implicitly present placeholders ?INDEX (= one-based index of the current iteration) and ?TOTAL (= total number of elements) will also be replaced in the snippet.

For an in-depth discussion, see For-loops.

@format-date

  • parameters:
    • a date
    • a text describing the formatting for the date
  • results in a text containing the formatted date

This special function allows you to specify a custom date format. The second parameter should consist of a combination (separated by hyphens) of the following parts:

  • d for the day of the month in numbers (e.g., 9 or 24)
  • dd for the day of the month, with two digits (e.g., 09 or 24)
  • m for the number of the month (e.g., 2 for February, 11 for March)
  • mm for the number of the month, with two digits (e.g., 02 for February, 11 for March)
  • yy for the year, with two digits (e.g., 23 for 2023)
  • yyyy for the year, with four digits (e.g., 2023)
  • mmmm for the month, expressed as a full word (e.g., “février” in French)
  • wwww for the day of the week, expressed as a full word (e.g., “Monday”)
  • comma to literally insert a comma
  • separator options, to be inserted as the very first part
    • slashed to specify that slashes should be used as separators
    • spaced to specify that spaces should be used as separators
    • dotted to specify that dots (.) should be used as separators
    • concat to specify that nothing should be used as separators

When mmmm is included, then spaces will be used as separators between the various parts. Else, hyphens are used, except if the first part of the formatting text starts with slashed/spaced/dotted/concat.

Examples using 29 April 2023 (in English):

  • d-m-yyyy becomes 29-4-2023
  • dd-mm-yyyy becomes 29-04-2023
  • slashed-d-m-yyyy becomes 29/4/2023
  • dotted-d-m-yyyy becomes 29.4.2023
  • concat-d-m-yyyy becomes 2942023
  • mm-dd-yyyy becomes 04-29-2023
  • wwww-comma-d-mmmm-yyyy becomes Saturday, 29 April 2023

@format-plain-nr

  • parameter: a (whole or fractional) number
  • returns text
  • see also: @format-nr

Formats the given number as a plain number, without any decimals or thousands grouping.

Examples:

  • @format-plain-nr(100 / 3.0) results in “33”. Note that {100 / 3.0} would result in “33.3333” or “33,3333”, depending on the locale settings
  • @year-of(2019_01_16) will result in “2.019” or “2,019”, depending on the locale settings. However, @format-plain-nr(@year-of(2019_01_16)) will result in a plain “2019”

Note in the examples above that rounding to the nearest number will occur.

@format-nr

  • first parameter: a number with currency, or a (whole or fractional) number
  • second parameter: either a text containing a sample, or a whole number
  • returns text
  • see also: @format-plain-nr

If the second parameter is a text, then ClauseBase will format the first parameter in accordance with the sample given in the second parameter. ClauseBase will analyse the way the sample is constructed, and try to mimic this when formatting the given number, taking into account the following features:

  • whether or not a decimals-symbol (comma or dot) is used, and — if a decimals-symbol is indeed used — the amount of decimal numbers
  • for currencies: the position of the currency (before or after the numbers) and whether to use a word (EUR, USD, …) or a symbol instead (€, $, …)

Examples (assuming continental European styling for numbers):

  • @format-nr(4567.89 EUR, "EUR 123") will result in “EUR 4.568”
  • @format-nr(4567.89 EUR, "123€“) will result in “4.568€”
  • @format-nr(4567.89 EUR, "€123") will result in “€4.568”
  • @format-nr(4567, "123.4567") will result in “4.567,0000”
  • @format-nr(4567, "123.4") will result in “4.567,0”
  • @format-nr(4567.89, "123") will result in “4.568”

If the second parameter is a whole number instead, then the number will be formatted in accordance with the default styling, with the specified amount of decimals numbers. Examples (assuming continental European styling for numbers):

  • @format-nr(4567.89 EUR, 0) will result in “4.568 EUR”
  • @format-nr(4567.89 EUR, 1) will result in “4.567,9 EUR”
  • @format-nr(4567 EUR, 2) will result in “4.567,00 EUR”
  • @format-nr(4567, 4) will result in “4.567,0000”
  • @format-nr(4567.789, 4) will result in “4.567,7890”

Note in the examples above that rounding to the nearest number will occur.

@french

  • no parameters
  • returns true or false
  • see also: @dutch and @english

For example, @french — no parameters or parentheses necessary — would return true if the currently active language is French, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@french) will return true if any other language but French is currently active.

@fullduration

Converts the duration into text, according to the current language. For example, @fullduration(5 months) will be converted into five months in English.

@fullcurrency

  1. parameter: currency
  2. returns text
  3. see also: @fullnr and @dynamic-fullnr and @fullduration

Converts the currency-number into text, according to the current language. Unlike @fullnr, the @fullcurrency:

  • also converts the currency itself into words, depending on the language
  • will convert the fractional part into cents, penny or whatever the fractional part is called in that currency

For example, in English, @fullcurrency(123.45 USD) will be converted into “one hundred and twenty-three United States dollars and forty-five cents“, while @fullcurrency(23.4 NOK) will be converted into “twenty-three Norwegian kroner and forty øre“.

For most currencies, this function will even dynamically switch between the singular and plural word used for the currency and its fractional part. For example, @fullcurrency(1.30 EUR) will be converted into “one euro and thirty cents“, while @fullcurrency(2.01 EUR) will be converted into “two euros and zero one cent”.

@fullmonth

  • parameter: a number between 1 and 12
  • returns the month as text, in the current language

For example, @fullmonth(8) will return “août” in French, “August” in English or “augustus” in Dutch.

@fullnr

Converts the amount into text, according to the current language. If a floating point number is passed, then the part after the decimal point is also included. If a currency is passed, then currency is also added. Examples:

  • @fullnr(365) will result in three hundred and sixty-five in English
  • @fullnr(365) will result in three hundred and sixty-five in English
  • @fullnr(12.340 EUR) will result in douze virgule trente-quatre EUR in French
  • @fullnr(1234.56) will result in duizend tweehonderdvierendertig komma zesenvijftig in Dutch

The maximum number you can use in ClauseBase, is 99.999.999.999 (99 billion etc).

@german

  • no parameters
  • returns true or false
  • see also: @english

For example, @german — no parameters or parentheses necessary — would return true if the currently active language is German.

Tip: you can easily invert the behaviour of this special function: not(@german) will return true if any other language but German is currently active.

@get

  • first parameter: a list
  • second parameter: a whole number
  • see also: @nth

Returns the element at the specified index within the (repeating) list.

Returns nil when the index is not found. (If you want to see an error-result instead, please use @nth).

Examples:

  • @get(@list(100, 200, 300), 1) will result in 100
  • @get(@list(100, 200, 200), 55) will result in nothing

Note that — unlike most programming languages — the index is one-based, i.e. the first index is one and not zero.

@greek

  • no parameters
  • returns true or false

For example, @greek — no parameters or parentheses necessary — would return true if the currently active language is Greek, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@greek) will return true if any other language but Greek is active.

@has-definition

Returns true if the specified concept currently has any kind of definition assigned to in the document/binder (i.e., either an integrated definition or an autonomous definition).

For example, @has-definition(#employee) will return true if some definition has been assigned to concept “employee” through the terms-pane of Assemble Document. Note that this function will also return true when a definition has been assigned, but no definition-list is currently present in the document/binder — if this possibility exists, then you should also check for @definitionlist-present.

Tip: you can easily invert the behaviour of this special function: not(@has-definition(#employee)) will return true if no definition is assigned to concept employee.

@has-autonomous-definition

Like @has-definition, but only returns true if the defined term has an “autonomous” definition assigned to it, i.e. a real definition that will separately show up in the definition list, as opposed to some regular clause that simulatenously acts as a definition.

Tip: you can easily invert the behaviour of this special function: not(@has-autonomous-definition(#employee)) will return true if no autonomous definition is assigned to concept employee.

@has-integrated-definition

Like @has-definition, but returns true if the defined term has an integrated definition assigned to it, i.e. a regular clause that contains, and simulatenously acts as, a definition — as opposed to a real definition that will separately show up in the definition list.

Tip: you can easily invert the behaviour of this special function: not(@has-integrated-definition(#employee)) will return true if no integrated definition is assigned to concept employee.

@hides-definition

Returns true if the specified concept currently has a “don’t show a definition” assigned to it in the document/binder (i.e. shown in blue in the terms pane).

Tip: you can easily invert the behaviour of this special function: not(@hides-definition(#employee)) will return true if it is not the case that a “don’t show a definition” is assigned to concept employee.

@highlight, @highlight-red, @highlight-green, @highlight-yellow

  • parameter: something that resolves into text
  • returns that text with a highlighted background
  • see also: @placeholder

This special function is similar to the @placeholder special function, in that it highlights the text in its sole argument. However, there are two important differences:

  • @highlight will not insert any other characters (such as square brackets) that may get inserted according to the placeholders-styling (part of the References styling)
  • the color of the @highlight is only equal to the color of the placeholders-styling if you use @highlight. If, instead, you use @highlight-red, the background will always be in red, irrespective of the setting of the placeholders-styling. The same for @highlight-green and @highlight-yellow.

@hungarian

  • no parameters
  • returns true or false

For example, @hungarian — no parameters or parentheses necessary — would return true if the currently active language is Hungarian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@hungarian) will return true if any other language but Hungarian is active.

@if

  • first parameter: a true/false value
  • second and third parameter: any kind of value
  • see also: @case, @switch and @when

Returns the second parameter if the first parameter is true, otherwise returns the third parameter.

This function can be used to create conditions within a parameter list, which can come in handy to avoid overly complex nesting of { … } conditions.

Examples:

  • @if(5 > 4, "alpha", "beta") will result in alpha
  • @if(#contract^value > 100, "large value", "low value") will result in “large value” when the datafield #contract^value is higher than 100, otherwise it will result in “low value”

@image

See How to insert images

@implemented

Returns true if the specified #concept or §cross-tag is implemented in the document, i.e. if some clause is present that textually represents this concept or cross-tag. (This will technically be the case when some clause contains an “implements” link towards the concept, respectively contains that cross-tag.)

Tip: you can easily invert the behaviour of this special function: not(@implemented(#concept)) will return true if clause is currently implementing that concept.

@implemented-all

Returns true if all of the #concepts or §cross-tags mentioned as parameters have been implemented. Returns false if @implemented is false for any of those.

Tip: you can easily invert the behaviour of this special function: not(@implemented-all(#employee, #contract, #started)) will return true if any of those three concepts is not implemented by a clause.

@implemented-any

Returns true if any of the concepts of §cross-tags mentioned as parameters have been implemented. Returns false if @implemented is false for all of those.

Tip: you can easily invert the behaviour of this special function: not(@implemented-any(#employee, #contract, #started)) will return true if none of those three concepts is implemented by a clause.

@in-binder

  • no parameters
  • returns true or false

Returns true if inside a Binder (i.e., if there are one or more subdocuments part of a Binder). Returns false in a standalone document.

Tip: you can easily invert the behaviour of this special function: not(@in-binder) will return true when working in a regular document.

@in-browser

Returns true if the clause/document/binder is shown on the screen (within the browser); returns false if it is being exported by the server.

The most interesting use case for this function is to allow you to only show a certain element (e.g., an introductory paragraph) on the screen, or instead only in the PDF/DOCX output.

Tip: you can easily invert the behaviour of this special function: not(@in-browser) will return true when generating PDF/DOCX input.

@in-browser

Returns true if the clause/document/binder is shown on the screen (within the browser); returns false if it is being exported by the server.

The most interesting use case for this function is to allow you to only show a certain element (e.g., an introductory paragraph) on the screen, or instead only in the PDF/DOCX output.

Tip: you can easily invert the behaviour of this special function: not(@in-browser) will return true when generating PDF/DOCX input.

@in-pdf

Returns true if the clause/document/binder is being exported to a PDF-file by the server (as opposed to being shown on the screen (within the browser), or being exported to DOCX).

The most interesting use case for this function is to allow you to only show a certain element (e.g., an introductory paragraph) in the PDF-file.

Note that this function will currently not take into account the browser-side export to PDF.

@in-docx

Returns true if the clause/document/binder is being exported to a DOCX-file by the server (as opposed to being shown on the screen (within the browser), or being exported to PDF).

The most interesting use case for this function is to allow you to only show a certain element (e.g., an introductory paragraph) in the DOCX-file.

Note that this function will currently not take into account the browser-side export to DOCX.

@in-language

  • first parameters: either a datafield or a #concept
  • second parameter: a two-character string referring to the language (“en”, “nl”, “fr”, “lt”, “de”, …)
  • returns text (or nothing)
  • see also: @multi-language

When a text-datafield (#concept^datafield) is passed as a parameter, this function will return the value of that datafield in the specified language.

When a #concept is passed as a parameter, this function will return the current concept-label for that concept in the specified language.

In both scenarios, this function can help constructing multi-language documents. In particular, this function allows you to use phrases such as “Président / Chairman” in a paragraph that is prohibited from being translated in a multi-language output.

For example, assume that your main language is French and that you want to translate the French clauses to English, whereby the concept-label #president gets outputted as “Président” in French and “Chairman” in English. In the signature box — which should obviously not get translated — you can then insert the following text in the French version: 

#president / @in-language(#president, "en")

This would then output as “Président / Chairman”. When you would change the concept-label, it would immediately get updated as well.

Similarly, if the function of a certain person would get stored in a multi-language text-datafield, you could use @in-language(#signatory^function, "en") in the uni-language signature box to pull the English data from the datafield.

@index

  • no parameters
  • returns a whole number

@index — no parameters or parentheses necessary — returns the current iteration number if this function is called from within a “loop”, i.e. when the software cycles between the elements of a list. This is for example the case when repeating a row in a table, or when going through repeating clauses. @index will return zero if used outside a loop.

For example, if #customer^name is a repeating list that contains the names “John Smith”, “Jane Doe” and “Marie Thompson”, then the following output would be produced in a table with a repeating-row . The @index starts at 1, and is then incremented with each additional row, until the end of the loop.

Note that (unlike most programming languages) the returned number is one-based, i.e. the first iteration in a loop will be one (not zero).

To get the row-index in the context of a Q&A column condition, use @row-index instead.

@insert-document

  • parameters:
    • #reference to another document
    • true/false: insert as separate pages? If set to true, then the software will insert the content on a separate page (using section breaks in MS Word, and including any header/footer of the source document).
    • true/false: use the layout of the “host” document for the inserted document? If set to true, then all the layout settings of the host document will get copied into the inserted document.
    • true/false: use the concept-labels of the host document for the inserted document? If set to true, then all the conceptlabels of the host document will get copied into the inserted document, so that the terminology will be identical. If not set to true, then the conceptlabels stored in the inserted document will get used for that document.
    • true/false: use the datafields of the host document for the inserted document? If set to true, then all datafields of the host document will get copied into the inserted document. If not set to true, then only the datafields for which values are stored in the inserted document itself, will be filled in in the inserted document.
    • true/false: ensure that the inserted document has its own numbering, separate from the host document? If set to true, then the host document and the inserted document will have different numbering lists, so that the numbering will not clash
  • Inserts the specified document at this point.
  • see also @msword-pages, which also explains how the numbering separation works

This function will insert another document into the “host” document. The different parameters allow you to specify to which extent the two documents should be similar or independent.

Note that the output of this special function will only be visible in the downloaded DOCX/PDF file (not in the browser).

@intersection

  • parameters: two lists (the second parameter will be automatically converted to a list)
  • returns a list
  • see also: @difference and @union

Takes the first list, and removes each element that does not also appear in the second list.

Examples:

  • @intersection(@list(1, 2, 3), @list(3)) will result in a list with element 3
  • @intersection(@list(1, 2, 3), 3) will result in a list with element 3 (note that the second parameter was automatically converted to a list)
  • @intersection(@list(1, 2, 3), @list(1, 2, 3)) will result in a list with elements 1, 2 and 3
  • @intersection(@list(1, 2, 3), @list(4, 5, 6)) will result in an empty list

@is-days

Returns true if the duration is currently specified in days.

Tip: you can easily invert the behaviour of this special function: not(@is-days(#concept^datafield)) will return true if the specified datafield is not specified in days.

@is-duplicate

  • parameter: a list
  • returns a new list in which each item is replaced by either true or false
  • see also: @distinct

This function has a fairly advanced use case. It takes in a list of elements, and then returns a new list in which element is replaced by either true or false, depending on whether the element duplicates a previous element.

For example, @is-duplicate(@list("alpha", "beta", "gamma", "alpha")) will return @list(false, false, false, true) because element alpha is present twice in the list.

This function can be interesting in situations where you need to show a list that potentially contains duplicates, and you want to create a condition for removing those duplicates. For example, you may have a table that was completed by an end-user in the Q&A, and you want to avoid showing rows that happen to duplicate a previous row. See an example on our discussion forum.

@is-male

Returns true if the current conceptlabel of the specified concept is set to male.

For example, @is-male(#employee) will return true if the conceptlabel used for concept “employee” is currently set to a word with male gender.

Tip: you can easily invert the behaviour of this special function: not(@is-male(#employee)) will return true if concept “employee” is currently set to a word with neutral or female gender.

@is-months

Returns true if the duration is currently specified in months.

Tip: you can easily invert the behaviour of this special function: not(@is-months(#concept^datafield)) will return true if the datafield is not currently specified in months.

@is-female

Returns true if the current conceptlabel of the specified concept is set to female.

For example, @is-female(#employee) will return true if the conceptlabel used for concept “employee” is currently set to a word with female gender.

Tip: you can easily invert the behaviour of this special function: not(@is-female(#employee)) will return true if concept “employee” is currently set to a word with neutral or male gender.

@is-neutral

Returns true if the current conceptlabel of the specified concept is set to neutral gender (for those languages that support it, such as Dutch).

For example, @is-neutral(#employee) will return true if the conceptlabel used for concept “employee” is currently set to a word with neutral gender.

Tip: you can easily invert the behaviour of this special function: not(@is-neutral(#employee)) will return true if concept “employee” is currently set to a word with male or female gender.

@is-plural

  • parameter: a defined term (#concept)
  • returns true or false
  • see also @is-singular

Returns true if the preferred number for the defined term is plural; otherwise returns false.

For example, @is-plural(#employee) will return true if the conceptlabel used for concept “employee” defaults to the plural form.

Tip: you can easily invert the behaviour of this special function: not(@is-plural(#employee)) will return true if concept “employee” is not currently set to a plural word.

@is-quarters

Returns true if the duration is currently specified in quarters.

Tip: you can easily invert the behaviour of this special function: not(@is-quarters(#concept^datafield)) will return true if the datafield is not currently specified in quarters.

@is-singular

  • parameter: a defined term (#concept)
  • returns true or false
  • see also @is-plural

Returns true if the preferred number for the defined term is singular; otherwise returns false.

For example, @is-singular(#employee) will return true if the conceptlabel used for concept “employee” defaults to the singular form.

Tip: you can easily invert the behaviour of this special function: not(@is-singular(#employee)) will return true if concept “employee” is not currently set to a singular word.

@is-subset

  • parameters: two lists
  • returns true if the first list is a subset of the second list

This function returns true when all the elements of the first list are also present in the second list. Note that if the first set is empty, this will always return true.

For example, @is-subset(@list("alpha", "beta"), @list("alpha", "gamma", "beta", "delta")) will return true, while @is-subset(@list(5), @list(6, 7, 8)) will return false.

Tip: you can easily invert the behaviour of this special function: not(@is-subset(@list("alpha", "beta"), @list("alpha", "gamma", "beta", "delta"))) returns false.

@is-valid-date

  • parameters: a number for the year, a number of the month and a number for the day of the month
  • returns true or false
  • see also @construct-date

Returns true if the duration is valid. For example, @is-valid-date(2021, 2, 24) would be valid (because 24th February, 2021 is a valid) date, while @is-valid-date(2021, 2, 31), because 31st of February is invalid.

Tip: you can easily invert the behaviour of this special function. For example, {@not(@is-valid-date(#concept^year, #concept^month, #concept^day)): !! invalid date specified !! | else: @construct-date(#concept^year, #concept^month, #concept^day) } would print an error message if the date is invalid, while it would print that date if it is effectively valid.

@is-weeks

Returns true if the duration is currently specified in weeks.

Tip: you can easily invert the behaviour of this special function: not(@is-weeks(#concept^datafield)) will return true if the datafield is not currently specified in weeks.

@is-years

Returns true if the duration is currently specified in years.

Tip: you can easily invert the behaviour of this special function: not(@is-years(#concept^datafield)) will return true if the datafield is not currently specified in years.

@italian

  • no parameters
  • returns true or false

For example, @italian — no parameters or parentheses necessary — would return true if the currently active language is Italian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@italian) will return true if any other language but Italian is active.

@japanese

  • no parameters
  • returns true or false

For example, @japanese — no parameters or parentheses necessary — would return true if the currently active language is Japanese, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@japanese) will return true if any other language but Japanese is active.

@latvian

  • no parameters
  • returns true or false

For example, @latvian — no parameters or parentheses necessary — would return true if the currently active language is Latvian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@latvian) will return true if any other language but Latvian is active.

@last-day-of-month

Returns the date of the last day of the month in the specified date.

For example, @last-day-of-month(2019_02_05) returns 28th February 2019.

@last-level

  • single parameter: a reference (e.g. §#concept or §tag)
  • returns the specified parameter, flagged to only show the last level in a numbering-set
  • see also @drop-doc-ref, @short-ref and @long-ref

Drops the “context” and prefix (“clause”, “section”, “article”, etc.) of a cross-reference, so that only the last level of numbering is shown.

For example, if §liability would be a reference to cross-tagged clause, printed as clause 1.2.3.(b), then @last-level(§liability) would result in merely (b). Note that also the prefix-word (in the example “clause”, but this will change depending on the language and reference styling) gets dropped.

The “last level” will coincide with the number printed at the left side of a clause by MS Word. So, depending on how the numbering styling is defined, the “last level” is not necessarily the “last number” for MS Word. For example:

  • In a typical “legal numbering” styling (which also happens to be the default in ClauseBase), the level numbering will consist of “1.” for the first level, “1.1.” for the second level, “1.1.1.” for the third level, etc. In such situation, the result of @last-level for a clause at level 3 will be the full set “1.1.1.” (= the number printed by MS Word on the left side of the clause), so not simply the last digit “1”.
  • Conversely, if you would define a numbering system such as “I.” for the first level, “A.” for the second level and “(i)” for the third level, the “last level” for a clause at level 3 will consist of “(i)”.

Accordingly, this special function is most relevant for two situations:

  • You are referring to a specific bullet (i.e., a paragraph started with an asterisk * in the ClauseBase editor) — such as 1.2.3.(b) in the example above — and you do not want to include the preceding levels.
  • You are using a numbering styling other than a typical “legal numbering”, e.g. with a style such as “I.A.(i)” in the example above.

@latest

  • parameter: two dates
  • returns: a date
  • see also: @earliest

Returns the latest of the two dates.

For example, @latest(2018_01_05, 2010_01_01) returns 5th January 2018.

@length

  • parameter: text
  • returns the number of characters found in the length
  • see also: @count and @trim

Returns the length of the text parameter, taking into account trailing or leading whitespace. For example, @length("alpha") returns 5, while @length(" alpha ") returns 7.

  • parameter: URL, and optionally an alternative presentation string
  • returns: a clickable hyperlink
  • see also: @email

Returns a clickable link to the specified URL. (If http:// of https:// is not added, http:// will be added automatically.)

For example, @link("www.clausebase.com") returns a clickable link to www.clausebase.com, while @link("www.clausebase.com", "ClauseBase website") returns a hyperlink to the same URL, but with the visible text being “ClauseBase website”.

@list

  • any number of parameters, of any kind
  • returns: a list
  • see also: @empty-list

Creates a list with the specified elements.

For example, @list("alpha", "beta") creates a list with two text elements, while @list(5, 6, 7) creates a list with thee numbers. The elements can be of any kind, so @list("alpha", 5, 5 months) is also valid. A list can even contain another list: @list(@list(3, 4), @list(5, 6)) creates a list that contains two other lists with numbers.

@list-if-all

  • parameters: one or more, of any type
  • returns either a list, or nothing

Returns all the parameters that are passed, if none of them are undefined. If any of them is undefined, then the result will be nothing.

For example, @list-if-all(5, 6, undefined) will be nothing, while @list-if-all(5, 6, 7) will result in @list(5, 6, 7).

@listbox

  • parameters:
    • list of texts (or list-of-text datafield)
    • optional index or text of the selected text item
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates an MS Word dropdown form field containing the specified text items
  • see also @cc-listbox and @cc-combobox

This function creates a dropdown list form field in MS Word that contains the specified text items. Note that, unlike the “Content Control” @cc-listbox and @cc-combobox (which rely on the new approach to form controls in MS Word), there is a maximum of 25 text items that can be inserted.

Also note that, unlike @cc-combobox, the end-user can only choose the predefined text-items from the dropdown list in MS Word. This traditional form field will not allow the end-user to choose his/her own text item, instead of the predefined text-items in the dropdown list.

When the (optional) second parameter is not passed, the first item will be selected in MS Word; if you want to have some other item preselected, you can either pass the (one-based) index of the item to select, or the text of the item you want to select. Optionally you can also pass a third parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

For example, both @listbox(@list("alpha", "beta", "gamma"), "beta") and @listbox(@list("alpha", "beta", "gamma"), 2) create a dropdown-list in MS Word, with the second item (beta) being selected.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

@lithuanian

  • no parameters
  • returns true or false
  • see also: @english

For example, @lithuanian — no parameters or parentheses necessary — would return true if the currently active language is Lithuanian.

Tip: you can easily invert the behaviour of this special function: not(@lithuanian) will return true if any other language is currently active.

@long-ref

  • single parameter: a reference (e.g. §#concept or §tag)
  • returns the specified parameter, flagged with a preference for the long version of the reference
  • see also @short-ref

When wrapping a reference in @long-ref, the software will prefer the long version of a reference (currently this is only relevant for document-references, which have both a long and short version). For example, even when the user’s styling is set to use the short version of a document’s title, @long-ref(§document) will return the long version, if available.

@lookup

  • parameters:
    • value to lookup
    • source-field (of type repeating-field)
    • target-field (of type repeating-field)
  • returns the value of the target-field that corresponds to the value to lookup, otherwise null

For example, assume you have a repeating-list #xxx^first-names and another repeating-list #xxx^last-names. @lookup("Daniel", #xxx^first-names, #xxx^last-names) will then result in the last name of Daniel (if found)

@lorem

  • parameter: a number between 1 and 5
  • returns a paragraph with the relative length indicated by its parameter

This function can help to quickly create a paragraph with dummy-text. It results in a paragraph with the famous lorem ipsum text that is either very short (nr. 1) or very long (nr. 5).

@lowercase

Returns the passed text, with all letters converted to lowercase. For example, @lowercase(‘He sees Fred walking in Stockholm’) results in he sees fred walking in stockholm.

@lsub

  • parameters: some text, and a maximum amount of characters to take from the left side
  • returns a sub-part of the specified text
  • see also @rsub and @sub

This function returns maximum X characters from input text.

For example, @lsub("alphabeta", 3) will return alp — i.e. the three first characters of the input text.

@matches

Returns true if the first parameter matches the structure of the second parameter (whereby an asterisk (*) means “zero or more characters” and a question mark (?) means “one character”), ignoring differences in leading/trailing whitespace or capitalisation.

For example, @matches(" Alpha Beta ", "*alpha*") and @matches("ALPHA", "al?ha") both return true.

Tip: you can easily invert the behaviour of this special function: not(@matches("ALPHA", "al?ha")) will return false.

@male-female

  • parameter: a defined term (#concept), some second parameter, and some third parameter
  • returns either the second parameter or the third parameter
  • see also @is-male and @is-female

Returns the second parameter if the specified concept is currently set to a male conceptlabel, and returns the third parameter if the specified concept is currently set to a female conceptlabel. Returns nothing if no conceptlabel is set, or the conceptlabel is set to the neutral form (in languages that have a neutral form, such as Dutch).

For example, @male-female(#employee, 5, 6) will return 5 if the current conceptlabel of #employee is set to male, and returns 6 if set to female. Similarly, @male-female(#employee, "Mr", "Ms") will return either Mr or Ms

@marginal

  • no parameters
  • inserts a marginal (in Dutch: “randnummer”) number, i.e. a number that is always increased within the document upon each use, followed by a period
  • see also @seq

For example, @marginal — no parentheses or parameters necessary — will ensure that a number will get inserted.

Note that the marginal is printed as a green “#nr” in the preview, so is not shown as a real number within the preview. Upon export to Word or PDF, it will be converted into a real number that increases with every paragraph in which you use it.

Tip: If you do not want to have a period inserted automatically, or you want to use different sequentially numbered lists, check out @seq.

@merge-tables

  • parameters: two or more snippets that contain tables
  • result: a new table in which the rows of the individual tables are glued together

As shown in the example below, the individual columns do not even have to be identical between the various sub-tables. For very complex tables, this function can therefore facilitate readability for the clause editor.

Another use case for this function, is to glue together repetitive rows that were created using the @for special function:

@max

  • parameters: a list of numbers of currency values
  • returns: the highest of those values
  • see also: @min

Returns the highest of a list of values. For example, @max(@list(3, 6, 2)) returns 6, while @max(@list(-8 EUR, 3 EUR, 5 EUR)) returns 5 EUR.

Before performing the calculation, all non-number values are removed from the list. You can mix freely floating-point numbers with whole numbers. However, if you specify any currency value, then all currency values must have the currency value (e.g., EUR).

@min

  • parameters: a list of numbers of currency values
  • returns: the lowest of those values
  • see also: @max

Returns the lowest of a list of values. For example, @min(@list(3, 6, 2)) returns 3, while @min(@list(-5 EUR, 3 EUR, 8 EUR)) returns -5 EUR.

Before performing the calculation, all non-number values are removed from the list. You can mix freely floating-point numbers with whole numbers. However, if you specify any currency value, then all currency values must have the currency value (e.g., EUR).

@minutes-in-timings

  • parameters: pairs of texts that designate the start and end timing (either formatted as “1000” or “10:00”)
  • returns: the number of minutes between the start and end timing
  • see also: @minutes-in-timing-lists and @minutes-to-timing

Calculates the aggregate duration, in minutes, of all pairs of timings. Each timing should be a piece text, formatted as either “900” or with a colon in between (9:00); the initial zero is optional (i.e., “9:35”, “935”, “09:35” and “935” are all considered equal).

For example, @minutes-in-timings("09:00", "1200", "1400", "16:30") calculates the duration of 09:00-12:00 (= 180 minutes) and 14:00-16:30 (= 150 minutes), so for a total of 330 minutes.

If an uneven number of parameters would be passed, then last parameter will simply be ignored. Similarly, parameters that cannot be treated as proper timings, will be ignored, and result in a duration of 0 minutes for that pair. For example, @minutes-in-timings("09:00", "1000", "alpha", "beta") will result in 60.

This function is particularly handy for creating timing tables, like working schedules.

@minutes-in-timing-lists

  • parameters: pairs of lists of texts that designate the start and end timing
  • returns: the aggregate total number of minutes between the start and end timings
  • see also: @minutes-in-timings and @minutes-to-timing

This function calculates the aggregate durations between the passed pairs of lists of texts. This is particularly useful for calculating the total duration of timing tables, such as working schedules.

For example, @minutes-in-timing-lists(@list("900", "1100", "13:00"), @list("12:00", "11:30", "13:45")) would calculate the total duration of:

  • 09:00 to 12:00 — 3 hours or 180 minutes
  • 11:00 to 11:30 — 30 minutes
  • 13:00 to 13:45 — 45 minutes
  • for a total of 255 minutes

The conversion of the texts is similar to what is described in @minutes-in-timings.

@minutes-to-timing

  • parameter: a number (which designates a number of minutes)
  • returns: text, consisting of the number of hours and minutes, with a colon (:) in between
  • see also: @minutes-to-timing

This function converts the specified number to a a text formatted as hours:minutes. For example, @minutes-to-timing(135) will result in the text “2:15”.

@month-of

  • parameter: a date
  • returns a whole number
  • see also: @day-of and @year-of

Returns the month number (1 – 12) of the specified date.

For example, @month-of(2018_4_2) returns 4.

@months-between

Returns the number of full months between two dates.

Examples:

  • @months-between(2019_2_5, 2019_2_6) will result in 0
  • @months-between(2019_2_5, 2019_3_5) will result in 1
  • @months-between(2019_2_5, 2019_8_23) will result in 6

@months-in

Returns the number of months in the duration value.

@msword-pages, @msword-pages-own-nrs and @msword-fragment

  • first parameter: a #file reference
  • other parameters: a list of snippets
  • inserts one or more pages or paragraphs from an external MS Word file into the document
  • See also @insert-document

This is an advanced function, described separately.

@multi-language

  • no parameters
  • returns true or false
  • see also: @in-language

Returns true if the current document contains multiple languages at once (i.e., is printed with multiple columns). Note that this will never be the case when a document is shown within the browser.

Tip: you can easily invert the behaviour of this special function: not(@multi-language) will return true only one single language is being outputted.

@norwegian

  • no parameters
  • returns true or false

For example, @norwegian — no parameters or parentheses necessary — would return true if the currently active language is Norwegian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@norwegian) will return true if any other language but Norwegian is active.

@nrbox

  • optional parameters:
    • (whole or floating point) number datafield / value
    • the number of decimal places (digits after the comma/period)to enforce upon numbers inserted by the end-user in the .DOCX file
    • name (text) — this is an advanced parameter that you can probably ignore
  • creates an MS Word form containing the optionally specified parameter
  • see also: @currencybox and @textbox

This function creates a box in MS Word that optionally contains the specified value (it will be empty when no parameters are passed).

Optionally you can also specify the number of decimal places. When it is ommitted, then the corresponding values of the currently applicable styling will be used (for which the platform’s default is 4 decimal places). Note that MS Word only allows a fixed number of decimal places, and does not allow dropping unnecessary zeroes (e.g., if 2 decimal places would be used, then a value such as 6 will get formatted as 6,00 in metric style, or 6.00 in imperial style).

A final optional parameter contains the specified internal name, which will then show up in the form field’s options inside MS Word.

Examples:

  • @nrbox(5) will insert a box that contains the value “5”. When the end-user would insert a new value into that box in MS Word, it will get formatted with the number of digital places indicated by the platform (probably 4).
  • @nrbox(5.02, 2) will insert a box with value “5.02”. When the end-user would insert a new value into that box (e.g. the number 6), it will get formatted with 2 decimal places — so for example 6.00 or 6.00, depending on the applicable styling settings.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

@nth

  • first parameter: a list
  • second parameter: a whole number
  • see also: @get

Returns the element at the specified index within the (repeating) list.

Returns an error when the index is not found. (If you want a null-value instead, please use @get).

Examples:

  • @nth(@list(100, 200, 300), 1) will result in 100
  • @nth(@list(100, 200, 200), 55) will result in an error (only indices 1, 2 or 3 would be valid)

Note that — unlike most programming languages — the index is one-based, i.e. the first index is one and not zero.

@numbered-paragraphs

  • parameters: either a list, or one or more values (which may themselves be lists, from which the elements will then be extracted)
  • inserts numbered paragraphs
  • see also: @bullets and @enumerate

Converts the parameter into numbered paragraphs. This is roughly equivalent to what the various @enumerate functions do, but instead of bullets or inline-numbered paragraphs / texts, entire numbered paragraphs are being inserted.

As illustrated by the screenshot below, it is easiest to insert this special function at the start of a numbered paragraph; this way, it will take on the numbering of the former paragraph.

image
Note that the #content^paragraphs happens to be a list of text, with elements “aaa”, “bbb” and “ccc”.

@one-else

  • first parameter: a whole number (or a duration, for which the number will then be extracted)
  • second and third parameter: text
  • returns text
  • see also: @one-else-nr

Returns the second parameter if the first parameter is equal to 1 or -1. In all other cases, returns the third parameter.

This function is typically used as a shortcut form — see the examples below.

Examples:

  • @one-else(1, "unit", "units") will result in “unit”. It would be similar to writing {#some^datafield = 1: unit | else: units}
  • @one-else(3, "unit", "units") will result in “units”

@one-else-nr

  • first parameter: a whole number (or a duration, for which the number will then be extracted)
  • second and third parameter :text
  • returns the number, followed by the text
  • see also @one-else

Returns the number, followed by:

  • the second parameter if the first parameter is equal to 1 or -1;
  • in all other cases, returns the third parameter.

This function is typically used as a shortcut form — see the examples below.

Examples:

  • @one-else-nr(1, "unit", "units") will result in “1 unit”. It would be similar to writing {#some^datafield = 1: 1 unit | else: #some^datafield units}
  • @one-else-nr(3, "unit", "units") will result in “3 units”

@open-qa

  • parameters: a #filename pointing to some Q&A file, and a caption
  • returns a hyperlink
  • see also @link

Creates a hyperlink to an existing Q&A, with the caption set to the second parameter. When clicked, that Q&A will open (assuming the user has sufficient rights).

For example, when you would insert @open-qa(#license-agreement, "License Agreement"), the software will show a hyperlink entitled “License Agreement” (shown in blue, as a typical hyperlink). When clicked, that hyperlink will open the Q&A associated with #license-agreement.

You will most likely want to wrap this special-function within a @in-browser condition, as it only makes sense on screen (i.e., should not be shown in a DOCX or PDF file).

@ord

  • single parameter should be a number
  • returns a text contain the ordinal of the specified number
  • see also @short-ord

Returns the ordinal of the specified number, in the current language. Up to 20, this function returns the number in full — for example, @ord(15) returns fifteenth in English or quinzième in French. Above 20, the short version is used — for example, @ord(156) returns 156th in English or 156e in French

@pagecount

  • no parameters
  • inserts a special Word-field that contains the total number of pages in the entire Word-document

For example, @pagecount — no parameters or parentheses necessary — would return “15” if that happens to be the total number of pages.

Note that the @pagecount cannot be calculated in the browser (i.e., will only export in Word or PDF).

Within MS Word, the number of pages is inserted as a so-called “field”, so it can automatically update when the actual number of pages would change. (You may have to update the fields by selecting the text and pressing F9.)

@pagenr

  • no parameters
  • inserts a special Word-field that contains the current page number in the entire Word-document

For example, @pagenr — no parameters or parentheses necessary — would return “15” if that happens to be the current page.

Note that @pagenr cannot be calculated in the browser (i.e., will only export in Word or PDF).

Within MS Word, the page number is inserted as a so-called “field”, so it can automatically update when the actual number of pages would change. (You may have to update the fields by selecting the text and pressing F9.)

@para

  • parameter: some text
  • returns the specified text, preceded by the paragraph symbol (§) and a space
  • see also @paras

This special function allows you to easily refer to statutory articles / sections, circumventing the fact thatthe paragraph-symbol has special (cross-referencing) meaning in ClauseBase. For example, ... as stated in @para("12.3"), it is ... will be converted into ... as stated in § 12.3, it is ...

@paras

  • parameter: some text
  • returns the specified text, preceded by two paragraph symbols (§§) and a space
  • see also @para

This special function allows you to easily refer to statutory articles / sections, circumventing the fact thatthe paragraph-symbol has special (cross-referencing) meaning in ClauseBase. For example, ... as stated in @paras("12.3 - 12.6"), it is ... will be converted into ... as stated in §§ 12.3 - 12.6, it is ...

@percent-divide

  • parameters: two numbers
  • returns a number

Divides the first number by the second number, multiplies the result by 100, and returns the final result. Typically used to calculate a percentage. 

For example, @percent-divide(5, 20) returns 25,00 — because 5 is 25% of 20.

@placeholder

  • parameter: text (or some parameter that can be converted to text)
  • returns a placeholder with the specified text
  • see also: @highlight

The placeholder will be formatted in accordance with the placeholders-styling (part of the References styling).

Tip: if you only want the highlight, but none of the characters that may get inserted as per the References styling, then have a look at the @highlight function.

@possessive

  • parameter: text (or some parameter that can be converted to text)
  • returns the text with either 's or ' appended

Only supported in Danish, Dutch, English and Swedish. In all other languages, the word is returned as-is (unmodified).

In the supported languages, this function returns the word with either only an apostrophe, or both an apostrophe and the letter “s” appended. The idea is to return the possessive (genitive) form.

For example, in English, this adds both apostrophe and the letter “s” when the original word does not end on the letter “s” — e.g., house becomes house's, while series becomes series' . Slightly different rules apply for Dutch, Danish and Swedish.

Do note that the algorithm used is not perfect, and does not perform a lookup in the dictionary. A minority of words will therefore be incorrect in the possessive form.

@plural

  • parameter: #concept
  • returns text (label of the concept)
  • see also: @singular

Returns the label of the passed concept, in plural form if possible.

See a dedicated video that talks about this function.

@polish

  • no parameters
  • returns true or false

For example, @polish — no parameters or parentheses necessary — would return true if the currently active language is Polish, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@polish) will return true if any other language but Polish is active.

@portuguese

  • no parameters
  • returns true or false

For example, @portuguese — no parameters or parentheses necessary — would return true if the currently active language is Portuguese, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@portuguese) will return true if any other language but Portuguese is active.

@quarters-in

Returns the number of full quarters in the duration value.

For example, @quarters-in(2 years) will result in 8.

@question-enabled

This special function can only be used within Q&A expression conditions.

@range

  • parameters: two numbers
  • returns a list of numbers

Returns a list with numbers between the two passed numbers (including those numbers themselves).

For example, @range(1, 5)results in a list with elements 1, 2, 3, 4 and 5.

If the second number is smaller than the first number — e.g., @list(5, 3) — the resulting list will be empty.

@ref-if

Returns a reference if the concept is implemented, otherwise results in nothing. Calling @ref-if(#concept) is largely similar to calling {@implemented(#concept): §#concept}, but will not result in an error message if the concept would happen to not be implemented.

@ref-subclauses

Returns a reference to a range of references: the first subclause up to the last subclause (or only the first subclause, if there is only a single subclause). Returns an error if no subclauses can be found.

Example:

@ref-siblings-before

  • parameter: a #defined term, §cross-tag, §this or §nr reference
  • returns either a single reference, or a range of references
  • see also: @ref-subclauses, @ref-siblings-after

Returns a reference to a range of references: the first subclause of the target clause’s parent clause, up to the subclause before the target clause (or only the first subclause of the target clause’s parent clause, if there is only one clause before the target clause). Returns an error if no siblings can be found before the target clause.

Example:

@ref-siblings-after

  • parameter: a #defined term, §cross-tag, §this or §nr reference
  • returns either a single reference, or a range of references
  • see also: @ref-subclauses, @ref-siblings-before

Returns a reference to a range of references: the first sibling after the target clause, up to the last subclause of the target clause’s parent clause (or only the first sibling, if there is only one clause before the target clause). Returns an error if no siblings can be found after the target clause.

Example:

@ref-title

  • parameter: #concept
  • returns a reference, followed by the title of the referenced clause between parentheses
  • see also: @clause-title

Returns a reference if the concept is implemented, followed by the title of the referenced clause between parentheses. (If the concept is not implemented, it results in nothing).

For example, @ref-title(#liability) may result in article 2 (Liability)

@refs-and

  • parameters: cross-references — either tag-based or concept-based (intra-clause references such as §1 will not work)
  • see also: @refs-or, @refs-if-or and @refs-if-and

This special function allow you to insert multiple cross-references at once. The software will take care that:

  • all references are ordered in accordance with their appearance in the document/binder
  • all references are grouped per subdocument
  • duplicate words are avoided

For example, assume you have to insert tag-based cross-references to the clause on liability (art. 12.2 of the main body), confidentiality (art. 4 of the main body), pricing (article 3 of Annex A), documentation (article 4 of Annex A) and contacts (article 5 of Annex A).

  • If you simply insert “§liability, §confidentiality, §pricing, §documentation and §contacts”, then you end up with “clause 12.2, clause 4, clause 3 of Annex A, clause 4 of Annex A and clause 5 of Annex A”. ClauseBase treats all those cross-references separately, without regard to one another. Notice that (1) the words “clause” and “Annex A” get repeated needlessly, (2) the ordering of the first two clauses is wrong, because it just happens that liability is printed before confidentiality, and (3) there is no reference to the main document in the first two clauses.
  • Instead, you can use @refs-and(§liability, §confidentiality, §pricing, §documentation, §contacts), which results in a much cleaner “clauses 4 and 12.2 of the main document and clauses 3, 4 and 5 of Annex A”. (Notice the plural “clauses” instead of the singular “clause”).

@refs-or

  • parameters: cross-references — either tag-based or concept-based (intra-clause references such as §1 will not work)
  • see also: @refs-and, @refs-if-or and @refs-if-and

This special function allow you to insert multiple cross-references at once. The software will take care that:

  • all references are ordered in accordance with their appearance in the document/binder
  • all references are grouped per subdocument
  • duplicate words are avoided

For example, assume you have to insert tag-based cross-references to the clause on liability (art. 12.2 of the main body), confidentiality (art. 4 of the main body), pricing (article 3 of Annex A), documentation (article 4 of Annex A) or contacts (article 5 of Annex A).

  • If you simply insert “§liability, §confidentiality, §pricing, §documentation or §contacts”, then you end up with “clause 12.2, clause 4, clause 3 of Annex A, clause 4 of Annex A or clause 5 of Annex A”. ClauseBase treats all those cross-references separately, without regard to one another. Notice that (1) the words “clause” and “Annex A” get repeated needlessly, (2) the ordering of the first two clauses is wrong, because it just happens that liability is printed before confidentiality, and (3) there is no reference to the main document in the first two clauses.
  • Instead, you can use @refs-or(§liability, §confidentiality, §pricing, §documentation, §contacts), which results in a much cleaner “clause 4 or 12.2 of the main document or clauses 3, 4 or 5 of Annex A”. (Notice that, unlike @refs-and, the word “clause” remains in singular)

@remove-this

  • Parameters: some reference, e.g. §this or §#concept
  • The effect is that the reference will be listed without the (translation of the) word “this” or “these”

References such as §this, but also other references that happen to refer to the current article, result in output such as “this article 5”. When you wrap the reference in a @remove-this call — e.g. @remove-this(§this) — then the word “this” or “these” will get dropped from the output.

This is particularly relevant for languages with grammatical cases, where the word “this” may need to be inflected according to complex grammatical rules. By using this special function, you will then be able to insert the relevant word manually.

@regex-find

  • parameters: some text and a “regular expression” pattern
  • returns:
    • (when no parentheses are used in the pattern): the first occurrence of some part of the text that matches the pattern
    • (when parentheses are used in the pattern): a list of all the matching parts between the parentheses
    • nothing, if no match was found
  • see also: @regex-find-all

This special function finds text on the basis of “regular expressions” — a powerful, standard mini-programming languages that describes the structure of texts (see for example www.regex101.com for an introduction).

Examples:

  • @regex-find("alpha beta gamma", "[b-h]") will return the first occurrence of either b, c, d, e, f, g, or h within the text, so will effectively return h
  • @regex-find("alpha beta gamma", "\S+") will return the first text that is bordered by a space, so will return alpha
  • @regex-find("alpha 123 gamma 456", "\d+") will return the first contiguous set of digits, so 123

An even more advanced use is to include parentheses within the pattern. In such case, this function will not return a piece of text, but will instead return a list of texts, where each text corresponds to the parenthesis group. Example:

  • @regex-find("alpha123beta456gamma789", "([a-z]+)(\d+)") will find the first occurrence of one or more contiguous letters followed by one or more digits. Because we use two parentheses-blocks, it will return @list("alpha", "123"). Note that without the parentheses, text alpha123 would be returned.

@regex-find-all

  • parameters: some text and a “regular expression” pattern
  • returns:
    • (when no parentheses are used in the pattern): a list with every occurrence of some part of the text that matches the pattern
    • (when parentheses are used in the pattern): a list of lists of all the matching parts between the parentheses
    • nothing, if no match was found
  • see also: @regex-find

This special function finds text on the basis of “regular expressions” — a powerful, standard mini-programming languages that describes the structure of texts (see for example www.regex101.com for an introduction).

Unlike @regex-find, this function will return all occurrences as a list.

Examples:

  • @regex-find-all("alpha beta gamma", "[b-h]") will find all occurrences of either b, c, d, e, f, g, or h within the text, so will effectively return @list("h", "b", "e", "g")
  • @regex-find-all("alpha beta gamma", "\S+") will return all pieces of text that are bordered by a space, so will return @list("alpha", "beta", "gamma")
  • @regex-find-all("alpha 123 gamma 456", "\d+") will return all contiguous set of digits, so @list("123", "456")

An even more advanced use is to include parentheses within the pattern. In such case, this function will not return a piece of text, but will instead return a list of lists of texts, where each text corresponds to the parenthesis group. Example:

  • @regex-find-all("alpha123beta456gamma789", "([a-z]+)(\d+)") will find all occurrences of one or more contiguous letters followed by one or more digits. Because we use two parentheses-blocks, it will return @list(@list("alpha", "123"), @list("beta", "456"), @list("gamma", "789")).

@regex-replace

  • parameters: some text, a “regular expression” pattern, and some other text that will act as a replacement
  • returns text

This function searches for occurrences within some text that match the “regular expression” pattern, and replaces those occurrences with the text of the last parameter. (Regular expressions, or regex in short, is a powerful, standard mini-programming languages that describes the structure of texts — see for example www.regex101.com for an introduction).

For example, @regex-replace("this is fine and binding", ".in.", "excellent") will result in this is excellent and excellenting because it replaces every occurrence of four letters in which the two middle letters are equal to “in” with the word “excellent”.

You can use $1, $2, etc. within the replacement text to refer to parenthesised groups within the pattern, e.g. to swap found items. For example, @regex-replace("this is nice and cool", "(nice)(.*)(cool)", "$3$2$1") will result in this is cool and nice because it searches for (1) the word “nice”, followed by (2) whatever other text, and (3) the word cool. Next, it replaces all the matched text parts with a replacement constructed by first taking part (3), then part (2) and then part (1).

@regex-split

Splits text on the basis of so-called “regular expression” (regex) patterns — a powerful, standard mini-programming languages that describes the structure of texts (see for example www.regex101.com for an introduction).

For example, @regex-split("alpha/_////beta_/_gamma", "[/_]+") splits the text on the basis of any number of consecutive slashes or underscores, and will thus result in a list with three elements (“alpha”, “beta” and “gamma”).

@refs-if-and

This function is identical to @refs-and, but drops invalid references (i.e., references that do not currently have a valid target).

@refs-if-or

This function is identical to @refs-or, but drops invalid references (i.e., references that do not currently have a valid target).

@reporting

  • no parameters
  • will return true when the document is currently shown in the reporting mode

For example, @reporting — no parameters or parentheses necessary — would return true if the document is currently shown in the reporting mode.

As described in the overview of the reporting mode, it is sometimes useful to wrap a part of a clause with the @reporting function, so that it will only be shown when the document is (not) in the reporting-mode. This function will be particularly useful to show/hide/modify a clause’s optional title when (not) in the reporting mode.

Tip: you can easily invert the behaviour of this special function: not(@reporting) will return true if the current mode is not the reporting mode.

@romanian

  • no parameters
  • returns true or false

For example, @romanian — no parameters or parentheses necessary — would return true if the currently active language is Romanian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@romanian) will return true if any other language but Romanian is active.

@round

  • parameter: a (whole or fractional) number
  • returns: a whole number
  • see also: @floor

Rounds the given number to the nearest integer. This function is similar to the automatic conversions applied by ClauseBase when converting between value types.

Examples:

  • @round(123.6) and @round(123.5) will both result in 124
  • @round(123.49) will result in 123

@row-index

  • no parameters
  • returns the (one-based) index of the current row whose Q&A column condition is being evaluated

Returns the value of the current table row’s index (starting with 1). This function can only be used within the visibility condition of a table cell.

Tip: to get the row-index outside the context of a Q&A column condition, use @index.

@rsub

  • parameters: some text, and a maximum amount of characters to take
  • returns a sub-part of the specified text
  • see also @lsub and @sub

This function returns maximum X characters from the right part of the input text.

For example, @rsub("alphabeta", 3) will return eta — i.e. the three last characters of the input text.

@russian

  • no parameters
  • returns true or false

For example, @russian — no parameters or parentheses necessary — would return true if the currently active language is Russian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@russian) will return true if any other language but Russian is active.

@semicolon-split

For example, @semicolon-split("alpha; beta; gamma") would result in a list with three elements (“alpha”, “beta” and “gamma”). Please note that the spaces around the semicolons are removed.

@seq

  • parameter: the name of the list
  • inserts a number field, i.e. a number that is always increased within the document upon each use with the same list-name
  • see also @seq

When using this function a “seq” field will be inserted in MS Word. Such field allows you to use different sequentially numbered lists in the same document. You may want to, for example, use such lists to number a list of images, or a list of parties, or a list of attachments, etc. Each time you invoke this function with the same list name as the parameter, the number will be increased.

Note that the number is printed as a green “#nr” in the preview, so is not shown as a real number within the preview. Upon export to Word or PDF, it will be converted into a real number that increases with every paragraph in which you use it.

Tip: A simpler function is the @marginal (no parameters required). It is always followed by a period, which may or may not be what you want.

@shared-condition

This special function can only be used within Q&A expression conditions.

@short-ord

  • single parameter should be a number
  • returns a text contain the short ordinal of the specified number
  • see also @ord

Returns the ordinal of the specified number, in the current language. This function always returns the “short” number — for example, @short-ord(15) returns 15th in English or 15e in French.

@short-ref

  • single parameter: a reference (e.g. §#concept or §tag)
  • returns the specified parameter, flagged with a preference for the short version of the reference
  • see also @long-ref

When wrapping a reference in @short-ref, the software will prefer the short version of a reference (currently this is only relevant for document-references, which have both a long and short version). For example, even when the user’s styling is set to use the long version of a document’s title, @short-ref(§document) will return the short version, if available.

@shrink-level

  • no parameters
  • returns the current shrinking-level as a number (0 if no shrinking applies, otherwise 1 to 4)

This special function is most relevant to disable/enable clauses based on the shrinking level that happens to apply. For example, inserting @shrinking-level > 2 would case a certain clause to only be shown when the shrinking level is 3 or 4.

@silence

  • single parameter: any type
  • results in either null, or the original parameter

Returns null when its single parameter is (or results in) an error. Otherwise just returns the parameter unchanged.

As suggested by its name, you can use this function to remove error-messages you are not interested in seeing for some reason.

@singular

  • parameter: #concept
  • returns text (label of the concept)
  • see also: @plural

Returns the label of the passed concept, in singular form if possible.

See a dedicated video that talks about this function.

@singular-plural

  • first parameter: a whole number
  • second parameter: a defined term (#concept)
  • see also: @one-else

Returns the singular form of the specified concept if the first parameter is equal to one; otherwise returns the plural form of the specified concept.

For example, @singular-plural(1, #concept) will return the singular form of the conceptlabel assigned to #concept.

@slovak

  • no parameters
  • returns true or false

For example, @slovak — no parameters or parentheses necessary — would return true if the currently active language is Slovak, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@slovak) will return true if any other language but Slovak is active.

@slovenian

  • no parameters
  • returns true or false

For example, @slovenian — no parameters or parentheses necessary — would return true if the currently active language is Slovenian, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@slovenian) will return true if any other language but Slovenian is active.

@sort

  • parameter: either a list, or one or more values (which may themselves be lists, from which the elements will then be extracted)
  • returns a sorted list of texts

Returns the passed list of texts, but alphabetically sorted. For example, @sort(@list(‘gamma’, ‘alpha’, ‘delta’)) results in a list with the same elements, but in the order ‘alpha’, delta’, ‘gamma’.

Be aware that the sorting procedure can result in surprises. For example, in @sort(@list(‘item 10’, ‘item 1’)), the ‘item 1’ will be put before the ‘item 10’, because the ‘item 1’ is shorter than ‘item 10’.

@space-split

For example, @space-split("alpha beta gamma") would result in a list with three elements (“alpha”, “beta” and “gamma”). Note that consecutive spaces are collapsed into one — for example, @space-split("alpha beta gamma") will also result in a list with three elements.

@str

  • parameters: anything convertible to text

Returns a text parameter that converts all of the parameters into text, and concatenates them together into a single text.

For example, @str(5, " ", 3 days, #employee) may — depending on the current concept-label for #employee — convert to “5 3 days the Employee”.

This can be especially useful when you want to deviate from ClauseBase’s default spacing system. For example, in the following text:

alpha " #beta " gamma

the spaces around the #beta will disappear in the final result, because this is typically what you want. If for some specific reason you intend to keep this spacing, you can use @str('alpha "', #beta, ' " gamma'). The conversion to @str will cause all parameters to be concatenated into a single text, that will not be further space-processed by ClauseBase.

@strictly-matches

  • paramaters: two text parameters
  • returns true or false
  • see also: @matches

Returns true if the first parameter matches the structure of the second parameter (whereby an asterisk (*) means “zero or more characters” and a question mark (?) means “one character”), taking into account differences in leading/trailing whitespace or capitalisation.

For example, @matches("alpha beta", "*alpha*") and @matches("ALPHA", "AL?HA") both return true, while @matches("ALPHA", "al?ha") will return false.

Tip: you can easily invert the behaviour of this special function: not(@matches("ALPHA", "AL?HA")) will return false.

@sub

  • parameters: some text, a starting position, and a maximum amount of characters
  • returns a sub-part of the specified text
  • see also @lsub and @rsub

This function returns a part of the original text, starting from the specified position, and with the specified maximum amount of characters.

For example, @sub("alphabeta", 3, 2) will return ph — i.e. two characters, starting from character position 3.

@sum

  • parameter: a (repeating) list
  • returns the sum of all the numbers in the list

For example @sum(@list(1, 2, 3)) returns 6.

@swedish

  • no parameters
  • returns true or false

For example, @swedish — no parameters or parentheses necessary — would return true if the currently active language is Swedish, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@swedish) will return true if any other language but Swedish is active.

@switch

  • parameters: a concatenation of tests and values
  • returns the first value for which the test is successful
  • see also @if, @when and @case

For example, @switch(1 > 3, "one is greater than three", 2 > 20, "two is greater than twenty", ("alpha" = "alpha"), "alpha is equal to alpha") will return “alpha is equal to alpha”.

@tab

  • parameter: the relative position (0 to 10) of the tab, as compared to
  • inserts a tab
  • see also @tab-u, @tab-d, @rtab, @rtab-u and @rtab-d

Inserts a tab at the specified position:

  • The r- versions insert a right-aligned tab (instead of the default left-aligned tab).
  • The -u versions insert a tab with preceding underscores.
  • The -d versions insert a tab with preceding dots.

For example, @rtab-u(5) inserts a right-aligned tab in the horizontal middle of the paragraph, preceded by dots.

Do not use tabs in table columns with automatic widths, because the results are unpredictable. Make sure that the table alignment is set to fill the entire width, and that the width of the columns is not automatically calculated.

Due to technical limitations, tabs cannot always be accurately shown within a browser. Combined with the fact that they are a leftover from the past, and that their use in MS Word should also be avoided where possible, we want to want to use tabs sparingly. Their most obvious use cases are to create forms where multiple elements need to be separated from each other using spaces or dotted leaders.

If you merely want to indent the first line of a paragraph, you are strongly advised to use % align left first line % or % align justified first line % at the beginning of the paragraph (or to set a custom styling with a first line indent). From an MS Word perspective, such a first-line-indented paragraph is much more desirable than a paragraph with an initial tab stop.

@terms-toc

This function inserts an index of references to defined terms that are used in the document. Such list can be used as an alternative or complement to a typical definition list.

This list consists of all the terms that are used somewhere in the document, to which either an explicit (autonomous) definiton was assigned, or for which some paragraph with an integrated definition (“shall have the meaning as set forth…”) is visible in the document.

Note that the list of included terms is not calculated in the same way as the definition lists, because references to integrated definitions are included irrespective of whether those are included in the definition list.

@text-part

  • parameter: a clause-part (e.g., “@ALPHA”)
  • converts the clause-part into a text

Converts the entire clause-part into a static text parameter. Please note that all newlines are thereby converted into spaces.

For example,

See @text(@ALPHA)

ALPHA = this is a test

and this also

would cause the text “this is a test and this also” (notice the space between the two parts) to be converted into a text-parameter. This text-parameter could then be used in other calculations.Only use this special-function when strictly necessary, because it slows down the recalculations.

@textbox

  • parameters:
    • optional text datafield (or text value)
    • optional name (text) — this is an advanced parameter that you can probably ignore
  • creates an MS Word form field containing the optional textbox
  • see also: @checkbox, @currencybox, @datebox, @listbox and @nrbox

This function creates a box in MS Word that optionally contains the specified text value (it will be empty when no parameters are passed). Optionally you can also pass a second parameter containing the specified internal name, which will then show up in the form field’s options inside MS Word.

Tip: when using form fields, you will probably want to protect the resulting MS Word document, so that only forms can be completed by the end-user.

Tip: You may also want to check out @cc-textbox, @cc-plaintextbox and @cc-multiline-textbox for the “Content Control” versions of text boxes, which uses the new approach to form controls of MS Word.

@toc

  • required parameter: the number of levels for the table of contents (1, 2, 3 or 4)
  • optional parameters:
    • insert a page-break before? (true/false, default value is false)
    • insert a page-break after? (true/false, default value is false)
    • insert the default title? (true/false default value is true)
  • see also: @toc-o1 @terms-toc

This function inserts a table of contents (including or without the title) with the specified number of levels at the position where the special function is invoked. The typical use case of this function is when the predefined options offered by the Clause9 interface are not enough (e.g., because you want to insert the TOC at a particular location), or when you want the insertion of the TOC to be dynamically configurable by the end-user. Examples:

  • @toc(4) inserts the title “Table Of Contents” (translated into the current language) with four levels of paragraph references, without a break before or after.
  • @toc(3, true, true) inserts the default title, three levels of paragraph references, preceded and followed by a break.
  • @toc(1, false, false, false) does not insert the default title, and inserts one level of paragraph references, without a break before or after.

If your users encounter issues when updating a TOC in Word, then you may want to have a look at @toc-o1.

@toc-o1

  • required parameters:
    • insert a page-break before? (true/false, default value is false)
    • insert a page-break after? (true/false, default value is false)
    • insert the default title? (true/false default value is true)
  • see also: @toc @terms-toc

This function inserts a table of contents (including or without the title) of one level at the position where the special function is invoked. Similar to @toc, the typical use case of @toc-o1 is when the predefined options offered by the ClauseBase interface are not enough (e.g., because you want to insert the TOC at a particular location), or when you want the insertion.

What differentiates @toc-o1 from @toc is that it creates a TOC of one single level, on the basis of the “outline level” of the paragraphs within the document. This requires some background explanation on how MS Word works internally.

Essentially, MS Word compiles a TOC by running through the entire document and collecting relevant paragraphs. Relevant paragraphs can either be determined on the basis of their MS Word style, or on the basis of the “outline level” of each paragraph (which is a property of every paragraph in MS Word).

The first option — looking for paragraphs with specific MS Word styles — is the more flexible option, and is therefore the default option used by Clause9. More specifically, Clause9 instructs MS Word to look for the styles for the “Document Title”, “Heading 1 Title”, “Heading 2 Title”, “Heading 3 Title”, and so on. However, as specified in Microsoft’s documentation, this breaks down for users who happen to have the locale settings of their computer set to use a semicolon instead of a comma as a list separator, which is on Windows the case for some versions of MS Word in non-Anglosaxon countries, and on a Mac often when the display language of MS Word is set to something other than English. When these users try to update the TOC, they will see an empty TOC and/or get a message that no relevant entries could be found in the document. Microsoft therefore recommends to not generate TOCs through the styles option when a document is being used in an international setting.

The second option — looking for paragraphs with a certain outline level — can be used as a fallback, but has its own share of problems. The documents generated by Clause9 can contain both headings (style “Heading 1”, “Heading 2”, etc.) and titles (“Heading 1 title”, “Heading 2 title”, etc.), and both have the same outline level, as illustrated by the levels of the paragraphs 2.1 and 3.1 in the following screenshot:

Using the outline-level based TOC beyond level 1 is therefore not a good idea in a legal text — and even when you use it through @toc-o1, you should be careful to avoid having non-title paragraphs at level 1, as they may end up in the TOC.

In summary, @toc-o1 should be used as a fallback to cope with the technical limitations of MS Word, for when @toc breaks down for your end-users. This is a very unfortunate situation that hopefully gets resolved in some future version of MS Word.

@to-paragraphs

  • parameter: some text
  • returns: the text converted into separate paragraphs

This function is exclusively intended to solve the problem that users may enter separate paragraphs into large answer boxes in a Q&A. For example, have a look at the following screenshot:

that reflects the contents of the following clause:

As you can seen in the first screenshot above, if you simply insert a text-datafield into a paragraph, any newlines inserted by the end-user will be ignored by the software. To effectively turn the end-user’s input into separate paragraphs, you have to wrap the text-field into @to-paragraphs.

@today

  • no parameters
  • returns a date

For example, @today — no parentheses or parameters necessary — will insert today’s date.

Note that this will cause a document to have a different output depending on the day it is exported to PDF or .DOCX.

@tracked-seq

  • parameters: list-name, item-name and formatting (all texts)
  • returns a new version of the formatting-text, with the number replaced
  • see also @tracked-seq-list and @seq

This special function and its sibling @tracked-list-seq offer a solution to authors who want to keep track of a collection of items, in the order they are inserted. Every time this special function is called, it will check in its inventory whether the combination of the specified list-name and item-name was previously called:

  • If this combination was not yet called before, then the software will check how many other items were are already stored in the specified list, and increase this number by one. This new number will then be assigned to the specified item-name, and that number will be used to replace the {1} in the formatting instruction. The software will then store the result in its memory.
  • if this combination was indeed already called before, then the previously calculated result will be returned.

The @tracked-seq-list will return a list of all the previously generated results, in the order they were initially called.

For example, assume you are creating a Binder and you need to add appendices for which the title depends on the order in which these appendices happened to be mentioned within the body of the main document. The following calls are potentially used, depending on various conditions attached to clauses in the body:

  • Clause 3.2: @tracked-seq("alpha", "pricing appendix", "Appendix {1}")
  • Clause 5: @tracked-seq("alpha", "ordered items appendix", "Appendix {1}")
  • Clause 7: @tracked-seq("alpha", "legal claims appendix", "Appendix {1}")
  • Clause 8: @tracked-seq("alpha", "ordered items appendix", "Appendix {1}")
  • Clause 9: @tracked-seq("alpha", "pricing appendix", "Appendix {1}")

Those calls will then result in Appendix 1, Appendix 2, Appendix 3, Appendix 2, Appendix 1 respectively. Notice that when the ordered items appendix was again requested, the software noticed that that item had been previously requested, and therefore returns the previously stored result.

You can then create a list of appendices through @tracked-seq-list, which would result in a list-of-text containing Appendix 1, Appendix 2 and Appendix 3. You can then feed that result to other functions, e.g. @enumerate-and.

@tracked-seq-list

  • parameter: list-name
  • returns a list of all the previously generated texts for the specified list
  • see also @tracked-seq

See the companion special function @tracked-seq for a detailed explanation.

@trim

  • parameter: text
  • returns trimmed text

Removes the text parameter without any whitespace (spaces, tabs, etc.) at the left of right side. For example, @trim(" alpha ") will return "alpha".

@turkish

  • no parameters
  • returns true or false

For example, @turkish — no parameters or parentheses necessary — would return true if the currently active language is Turkish, false otherwise.

Tip: you can easily invert the behaviour of this special function: not(@turkish) will return true if any other language but Turkish is active.

@uncapitalize

  • parameter: text
  • returns the text, with the first character forced to lowercase

For example, @uncapitalize("Alpha beta Gamma") will return "alpha beta Gamma", while @uncapitalize("alpha BETA GAMMA") will return its parameter unchanged.

@underscores

  • parameter: the number of desired underscores
  • returns the specified number of underscores, printed next to each other

In ClauseBase, an underscore is a special character (used, for example, to hard-code numbers). Simply inserting a set of underscores, by way of placeholder, will therefore result in an error message from the software.

Instead of writing @str("___") or {"___"}, you can write @underscores(3) to insert three underscores.

@union

  • parameters: one or more(which may themselves be lists, from which the elements will then be extracted)
  • returns a list
  • see also: @difference and @intersection

Takes the first list, and adds all elements from the second list that are not already present in the first list.

Examples:

  • @union(@list(1, 2, 3), @list(3)) will result in a list with elements 1, 2 and 3
  • @union(@list(1, 2, 3), @list(4)) will result in a list with elements 1, 2, 3 and 4
  • @union(@list(1, 2, 3), @list(4, 4, 4, 4)) will result in a list with elements 1, 2, 3, 4, 4, 4

@uppercase

Returns the passed text, with all letters converted to uppercase. For example, @uppercase(‘alpha beta gamma’) results in ALPHA BETA GAMMA.

@user-first-name

  • no parameters
  • returns the current user’s first name
  • see also @user-last-name

For example, @user-first-name — no parentheses or parameters necessary — could result in “Mary” if that is the current user’s first name.

@user-last-name

  • no parameters
  • returns the current user’s last name
  • see also @user-first-name

For example, @user-last-name — no parentheses or parameters necessary — could result in “Smith” if that is the current user’s last name.

@user-tags

  • no parameters
  • returns a text-list of all the tags assigned to the current user (also including the tags assigned to the user’s customer account and the tags assigned to the various groups of which the user is a member)

For example, @user-tags — no parentheses or parameters necessary — could result in a list containing “accounting” and “badgenumber-101” if these tags would happen to have been assigned to that user by the administrator.

@void

  • no parameters
  • results in an element that produces nothing in the printed document
  • see also: @black-hole

This function ultimately results in nothing, but is nevertheless useful in those situations where you technically have to insert something to comply with the technical grammar, but do not want anything to actually show up in the document.

In practice, this can for example be used to create the following structure, where you do not want anything to show up next to 1. (without the @void, the 1. would simply be ignored by ClauseBase because that paragraph is actually empty, so that the subclauses would be inadvertently moved one level up).

@week-nr

  • parameter: a date
  • returns a whole number

Returns the number (1 – 52) of the week within the year.

For example, @week-nr(2018_4_5) returns 14.

@weekday

  • parameter: a date
  • returns the day of the week
  • see also: @weekday-nr

Returns the name of the week day (e.g., “Monday” in English, or “lundi” in French) for the specified date.

@weekday-nr

  • parameter: a date
  • returns a whole number
  • see also: @weekday

Returns the number of the day (1 = Monday, 7 = Sunday) for the specified date.

@weeks-in

Returns the number of weeks in the duration value.

For example, @weeks-in(1 year) results in 52.

@weeks-between

Returns the number of full weeks between two dates.

Examples:

  • @weeks-between(2019_2_5, 2019_2_6) will result in 0 (only one day difference)
  • @weeks-between(2019_2_5, 2019_3_5) will result in 4

@when

  • parameters: a test-expression and a value
  • returns the value if the test-expression evaluates to true
  • see also @if, @case and @switch

For example, @when(1 > 0, "one is greater than zero") will return “one is greater than zero”, while @when(1 > 10, “one is greater than ten”) will return nothing.

@year-of

Returns the year of the specified date.

For example, @year-of(2018_4_2) returns the number 2018.

If the result of this function is directly inserted into the text, then you probably want to use @format-plain-nr to prevent thousands grouping symbols. For example, @year-of(2018_4_2) will result in “2.018” under continental European formatting, which is probably not what you want. To remove the period from the output, use @format-plain-nr(@year-of(2018_4_2)).

@years-in

Returns the number of years in the duration value.

For example, @years-in(4 year) results in 4, while @years-in(36 months) results in 3.

@years-between

Returns the number of full years between two dates.

Examples:

  • @years-between(2019_2_5, 2019_2_6) will result in 0 (only one day difference)
  • @years-between(2019_2_5, 2020_2_5) will result in 1
  • @years-between(2019_2_5, 2020_2_4) will result in 0 (just a day short of one full year)
Was this article helpful?
Dislike
Cross-references
Introduction to tables