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 @case @if @switch @when

@implemented @implemented-all @implemented-any

@in-browser

@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-apostrophe

@earliest @latest

@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

@one-else @one-else-nr

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

@difference @intersection @union @is-subset

@bullets @enumerate

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

@for

@list-if-all

@get @nth

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

@extract-currency @extract-number

@abs @floor

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

@marginal @pagecount

@percent-divide

@range

@round
References@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

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

@msword-pages and @msword-fragment

@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 @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 @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

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. Similarly, assigning the value false to a true/false datafield (visually represented as a checkbox that is not checked), will also cause the @assigned function to return true for that datafield, as will assigning the value 0 to a number datafield.

This will probably come as a surprise if you are new to thinking in data types.

@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

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.

@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:

@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.)

@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(‘just testing some words’) results in ‘Just Testing Some Words’.

@card-enabled

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

@case

  • 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”.

@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.

@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.

@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.

@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.

@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-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

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.

@fullcurrency

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.

@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

  • no parameters
  • returns true or false

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-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).

@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, "Mister", "Mrs") will return either Mister or Mrs.

@marginal

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

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.

@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:

@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

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 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

This is an advanced function, described separately.

@multi-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.

@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”

@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.)

@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

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

@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

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)

@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

@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.

@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.

@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)

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 ClauseBase 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.

@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.

@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

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