Conditions

@cascade

• one or more parameters of any type

• can return any type

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.

@cycle

• parameters:

  • a datafield

  • a concatenation of test-values and result-values

• runs through the test-values and returns the first result-value for which the test-value is equal to the value of the datafield

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

@explain

• parameters:

  • first parameter: a textual explanation for the end-user of the condition in the second parameter

  • second parameeter: a condition

This function is exclusively intended to clarify the Uncover functionality, particularly for complex conditions.

For example, assume you have the following snippet of text:

The first condition is somewhat complex due to the OR parameter. When visualised in the browser through the Misc > Uncover function (or in a DOCX through the Uncovered export), this results in the following explanation:

This technical breakdown is very helpful for the author of the clause. However, from the perspective of the end-user, this feels very unfriendly.

The @explain function can be a solution. It can be wrapped around the condition, to provide an end-user explanation of what the condition is really going on:

This will then result in a clean explanation in the browser and in the DOCX generated by the Uncovered export:

Things can easily get more complex when combining conditions, particularly when invoking special functions, because those are difficult to explain towards a non-technical audience. For example,

will result in the following complicated bullets, for which an @explain would really be helpful towards the end-user.

@if

• first parameter: a true/false value

• second and third parameter: any kind of value

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”

@if-value

• only parameter: some value

Returns the parameter if it is defined, otherwise returns undefined.

The use case of this function is to avoid that a placeholder would be shown because some datafield in Clause9 (or answer in ClauseBuddy) is not yet filled in. For example, in the following screenshot, you can see that the description datafield is not yet filled in, so a placeholder is shown in the first paragraph. If it is not desirable to show this placeholder, you can wrap the datafield in @if-value.

In Clause9, similar behaviour can be achieved by inserting an exclamation mark before a datafield:

However, such exclamation-mark is not available in ClauseBuddy. Accordingly, in ClauseBuddy, the best approach is to wrap an answer inside of an @if-value .

@implemented

• parameter: #concept or §cross-tag

• returns true or false

• see also: @assigned, @implemented-all and @implemented-any

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

• parameters: one or more #concepts or §cross-tags

• returns true or false

• see also: @assigned, @implemented and @implemented-any

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

• parameters: one or more #concepts or §cross-tags

• returns true or false

• see also: @assigned, @implemented and @implemented-all

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

• no parameters

• returns true or false

• see also: @in-pdf and @in-docx

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

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

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

@in-pdf

• no parameters

• returns true or false

• see also: @in-browser and @in-docx

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

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

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

@in-docx

• no parameters

• returns true or false

• see also: @in-browser and @in-pdf

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

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

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

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

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

@ref-if

• parameter: #concept

• returns a reference, or nothing

• see also: @implemented @refs-if-and @refs-if-or

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.

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

@switch

• parameters: a concatenation of tests and values

• returns the first value for which the test is successful

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

@when

• parameters: a test-expression and a value

• returns the value if the test-expression evaluates to true

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.