Text modification

@capitalize

• parameter: some text

• returns text

• see also: @capitalize-words, @lowercase, @uppercase

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

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

@capitalize-words

• parameter: text

• returns text

• see also: @capitalize, @lowercase, @uppercase

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

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

@capitalize-words

• parameter: text

• returns text

• see also: @capitalize, @lowercase, @uppercase

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

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

@comma-split

• split up a text with zero or more commas into a list of texts

• returns a list with texts

• see also: @semicolon-split, @regex-split and @space-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.

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

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

@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 Clause9 will format the first parameter in accordance with the sample given in the second parameter. Clause9 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.

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

@lowercase

• parameter: text

• returns text

• see also: @uppercase, @capitalize, @capitalize-words

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.

@matches

• paramaters: two text parameters

• returns true or false

• see also: @strictly-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.

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

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

Be aware that regular expressions are not completely cross-platform, i.e. there are some more advanced features that work differently in a browser (where Clause9 relies on JavaScript) and on the server when generating a DOCX/PDF file (where Clause9 relies on Java).

For example, the lookbehind operator ?<= works differently and non-ASCII characters are treated differently. If you rely on advanced features of Regex, then make sure you test your special function's input both on the screen and in DOCX/PDF.

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

See the warning below @regex-find concerning the cross-platform pitfalls of regular expressions.

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

See the warning below @regex-find concerning the cross-platform pitfalls of regular expressions.

@regex-split

• split up a text on the basis of regular expression patterns

• returns a list with texts

• see also: @comma-split, @semicolon-split and @space-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”).

See the warning below @regex-find concerning the cross-platform pitfalls of regular expressions.

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

@semicolon-split

• split up a text with zero or more semicolons into a list of texts

• returns a list with texts

• see also: @comma-split, @regex-split and @space-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.

@space-split

• split up a text with zero or more spaces into a list of texts

• returns a list with texts

• see also: @comma-split, @regex-split and @semicolon-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.

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

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

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

@uppercase

• parameter: text

• returns text

• see also: @lowercase, @capitalize, @capitalize-words

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