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.

@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

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

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

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

PreviousText structure NextUser

Last updated 8 months ago