Expression

An expression refers to either:

A literal value, such as a number (e.g. 123) or a piece of text (e.g. "Hello world"); or
A group of words or symbols that describes how to obtain a value (e.g. Contact.ShortName, Today()).

ContactsLaw allows the use of expressions in document templates, automatic descriptions for document types and workgroups, as well as various other areas. This is the basis for generating content that draws upon data from contacts, matters and so on.

Types of Expressions


Type	Example Expressions	Example Results	Remarks
Literal	`123` `"Hello world"`	`123` `"Hello world"`	To include double-quote characters inside a string literal, prefix with a backslash (i.e. `\"`).
Asset	`Contact` `Matter` `Address`		Assets do not produce any result directly, but can be used in conjunction with some functions, e.g. `Count(Contact)`might evaluate to `3` if the asset represented three parties on a matter.
Property	`Contact.ShortName` `Contact.Gender` `Matter.Code` `Address.Country`	`"John Smith"` `"Male"` `"678-1"` `"Australia"`	Properties belong to assets. If an asset represents multiple contacts/matters/etc then the expression produces multiple results. Unless you specify otherwise, multiple results appear as a list of values, separated by commas (e.g. `"John Smith, Fred Baker, Jane Doe"`).
Operator	`+`, `-`, `*`, `/` `=`, `<>`, `<`, `>`		Arithmetic operators compute numbers. Conditional operators produce either `Yes` or `No`.
Function	`IsNotEmpty(Contact.LastName)` `Plural("word")` `If(Count(Contact) < 3, "friends", "acquaintances")`	`Yes` `"words"` `"acquaintances"`	Functions compute a result based on their arguments (inputs). Function calls can be nested within each other.
Constant	`NewLine` `NewParagraph`	`"␊"` `"␍"`	Constant expressions provide a short-hand way of inserting frequently-used values, as well as text that cannot normally be entered directly (e.g. tab spaces).
Repetition	`current.ShortName` `current.Country` `index`	`"John Smith"` `"Australia"` `3`	These expressions can only be used inside a repetition block, where they correspond to either the current instance of the repeated asset or a number indicating how many times the block has been repeated so far.

Desktop App

The information in this section relates to a pre-release version of ContactsLaw and is not representative of the final product.

The Desktop App includes various features to assist in writing and utilising expressions:

Rich text editing - In situations where content may consist of formatted text and expressions, you can edit expressions directly. Text formatted as an expression appears in a monospaced font with a grey background.
Syntax highlighting - To improve readability, the various components of expressions are colour-coded. Syntax errors are underlined (in the same manner as spelling errors in normal text).
Automatic completion - Suggestions for assets, functions and other components of expressions appear as you type. You can double-click or press the Tab key to accept a suggestion.
Inline documentation - Hover the mouse over components of an expression to show the relevant documentation.
Previews - In many cases, you can toggle between editing an expression and previewing the result (using example data).

Operator Reference

This section documents each of the operators that can be used in expressions.

Mathematical

These operators work with whole and decimal numbers only.


Operator	Purpose
`+`	Add
`-`	Subtract
`*`	Multiply
`/`	Divide
`%`	Modulus (remainder)

At least one of the values must be a number; if the other is a number formatted as text then it will be treated as a number.

Comparison

These operators work with numbers and date/time values.


Operator	Synonym(s)	Purpose
`=`	`eq`	Is equal to
`<>`	`!=`, `neq`	Is not equal to
`<`	`lt`	Is less than
`<=`	`lte`	Is less than or equal to
`>`	`gt`	Is greater than
`>=`	`gte`	Is greater than or equal to

At least one of the values must be either a number or a date/time; if the other is a number formatted as text then it will be treated as a number, and if it is a date/time formatted as text then it will be treated as a date/time.

Conditional

These operators work with yes/no values.


Operator	Purpose
`and`	And (yes if both are yes)
`or`	Or (yes if either are yes)
`not`	Not (no if yes, yes if no)

Other types of values will be converted to yes or no according to the following rules:

Text - No if empty, "no", "false" or "0"; otherwise yes.
Number - No if zero; otherwise yes.

Text

These operators work with text.


Operator	Synonyms	Purpose
`&`	`+`	Concatenate (join)

Note: The + operator can be used for both addition and concatenation; if at least one value is a number then it will perform addition. Use the & operator to avoid ambiguity.

Function Reference

This section documents each of the functions that can be used in expressions. The documentation is also available within the Desktop App.

Text Functions

These functions operate on text.

An(word)

Produces 'a' or 'an' according to grammar rules for a particular word.

word - Word.

Filter(text, [allowed, ...])

Filters text to allow only specific values.

text - Text.
allowed - Allowed values.

IsAre(value)

When there are two or more values, produces 'are'. Otherwise, produces 'is'.

value - Number or set of values.

Lower(text)

Converts text to 'lowercase'.

text - Text.

Optional([values, ...])

Joins consecutive values together. If any value is empty, the result is also empty.

values - Any value.

Plural(word)

Converts a word to its plural.

word - Singular form of the word.

PluralOf(value, word)

Converts a word to its plural when there are two or more values.

value - Number or set of values.
word - Singular form of the word.

Possessive(word)

Adds a possessive apostrophe to a word according to grammar rules.

word - Word.

Replace(text, find, replace)

Replaces all occurrences of a particular word/phrase in the text.

text - Subject text.
find - Word/phrase to find. Can be a regular expression.
replace - Replacement text. Can include capture groups.

ReplaceWith(text, find, replace)

Replaces the entire value if it contains a particular word/phrase.

text - Subject text.
find - Word/phrase to find. Can be a regular expression.
replace - Replacement text. Can include capture groups.

Sentence(text)

Converts text to 'Sentence case'.

text - Text.

Title(text)

Converts text to 'Title Case'.

text - Text.

Upper(text)

Converts text to 'UPPERCASE'.

text - Text.

Number Functions

These functions operate on numbers.

Number(number, [thousands = Yes])

Formats a whole number as text.

number - Number.
thousands - Use thousands separator (Yes/No).

Decimal(number, [decimals = 2], [thousands = Yes])

Formats a decimal number as text.

number - Number.
decimals - Decimal places.
thousands - Use thousands separator (Yes/No).

Currency(number, [decimals = 2], [thousands = Yes])

Formats a currency value as text.

number - Number.
decimals - Decimal places.
thousands - Use thousands separator (Yes/No).

Min(set)

Calculates the smallest value in a set.

set - A set of values.

Max(set)

Calculates the largest value in a set.

set - A set of values.

Sum(set)

Calculates the sum of the values in a set.

set - A set of values.

Avg(set)

Calculates the average of a set.

set - A set of values.

NumberInWords(number)

Converts a number to words.

number - Number.

CurrencyInWords(number)

Converts currency to an amount in words.

number - Number.

WordsToNumber(text)

Converts words to a number.

text - Text.

WordsToCurrency(text)

Converts an amount in words to currency.

text - Text.

Ordinal(number)

Adds the ordinal suffix (st/nd/rd/th) to a number.

number - Number.

Conditional Functions

These functions are used to make decisions.

If(condition, yes, [no])

Tests a condition and gives a different value depending on the result.

condition - Yes/no.
yes - Value if true.
no - Value if false.

IsEmpty(value)

Tests whether a set or value is empty (yes/no).

value - Any value.

IsNotEmpty(value)

Tests whether a set or value is not empty (yes/no).

value - Any value.

AllEmpty(set)

Tests whether all of the values in a set are empty (yes/no).

set - A set of values.

AllNotEmpty(set)

Tests whether all of the values in a set are not empty (yes/no).

set - A set of values.

DefaultIfEmpty(value, [default, ...])

Provides a default for when a value is empty. Short-hand for: If(IsEmpty(value), default, value)

value - Any value.
default - Value if empty.

DefaultIfMultiple(value, default)

Provides a default for when there are two or more values. Short-hand for: If(Count(value) > 1, default, value)

value - Any value.
default - Value if multiple.

Not(condition)

Reverses the result of a condition (yes/no).

condition - Yes/no.

Contains(set, value)

Tests whether a set contains a particular item (yes/no).

set - A set of values.
value - Any value.

Intersects(set1, set2)

Tests whether two sets have any items in common (yes/no).

set1 - A set of values.
set2 - A set of values.

Case(value, [cases, ...])

Matches a value against a set of cases. See also: When and Else

value - Value to test.
cases - Cases to match.

When(value, result)

Specifies a result for a particular value in a Case function.

value - Value to match.

result - Result if matched.

Else(result)

Specifies a result for when nothing matches the value in a Case function.

result - Value if no match.

Date and Time Functions

These functions operate on date and time values.

Date(date, format)

Formats a date as text.

date - Date/time.
format - Date/time format. Can be pre-defined (e.g. DateStyle1) or a custom format

AddMinutes(date, minutes)

Adds a number of minutes to a date/time value.

date - Date/time.
minutes - Number of minutes. Use negative numbers to subtract.

AddHours(date, hours)

Adds a number of hours to a date/time value.

date - Date/time.
hours - Number of hours. Use negative numbers to subtract.

AddDays(date, days)

Adds a number of days to a date/time value.

date - Date/time.
days - Number of days. Use negative numbers to subtract.

AddWeekDays(date, days)

Adds a number of weekdays (skipping over weekends) to a date/time value.

date - Date/time.
days - Number of weekdays. Use negative numbers to subtract.

AddMonths(date, months)

Adds a number of months to a date/time value.

date - Date/time.
months - Number of months. Use negative numbers to subtract.

AddYears(date, years)

Adds a number of years to a date/time value.

date - Date/time.
years - Number of years. Use negative numbers to subtract.

SetTime(date, [hour], [minute])

Sets the time component of a date/time value.

date - Date/time.
hour - Hour (0-23).
minute - Minute (0-59).

SetTimeZone(date, tz)

Changes the time zone of a date/time value.

date - Date/time.
tz - Offset (-14 to 14).

Day(date)

Gets the day component of a date/time value.

date - Date/time.

Month(date)

Gets the month component of a date/time value.

date - Date/time.

Year(date)

Gets the year component of a date/time value.

date - Date/time.

Hour(date)

Gets the hour component (0-23) of a date/time value.

date - Date/time.

Minute(date)

Gets the minute component (0-59) of a date/time value.

date - Date/time.

Today()

Today's date.

Now()

Today's date, including the current time.

Days(date1, date2)

Gets the number of days between two date/time values.

date1 - Date/time.
date2 - Date/time.

Minutes(date1, date2)

Gets the number of minutes between two date/time values.

date1 - Date/time.
date2 - Date/time.

Years(date1, date2)

Gets the number of years between two date/time values, rounded down.

date1 - Date/time.
date2 - Date/time.

Age(date)

Gets the number of years that have elapsed since a particular date, rounded down.

date - Date/time.

MakeDate(year, [month], [day])

Constructs a date value from its year, month and day components.

year - Year number.
month - Month number (1-12).
day - Day number (1-31).

HoursAndMinutes(minutes)

Expresses a quantity of minutes in hours and minutes.

minutes - Number of minutes.

Set Functions

These functions operate on sets of values.

Set([values, ...])

Creates a set from one or more values.

values - Values.

Range(set, [start = 1], [count])

Creates a subset of a set.

set - A set of values or assets.
position - Starting position.
count - Number of items (maximum) to include.

Union(set1, set2)

Gets the union of two sets.

set1 - A set of values or assets.
set2 - A set of values or assets.

Except(set, excluded)

Gets the items in a set which do not appear in some other set.

set - A set of values or assets.
excluded - Values/assets to exclude.

Intersection(set1, set2)

Gets the intersection of two sets.

set1 - A set of values or assets.
set2 - A set of values or assets.

Sort(set, [smart = Yes])

Sorts the items in a set.

set - A set of values or assets.
smart - Whether to use natural language sorting rules.

RSort(set, [smart = Yes])

Sorts the items in a set in reverse order.

set - A set of values or assets.
smart - Whether to use natural language sorting rules.

NotEmpty(set)

Filters a set by excluding empty values.

set - A set of values or assets.

Unique(set)

Filters a set by excluding duplicate values.

set - A set of values or assets.

Each(set, expression)

Evaluates an expression for each item in a set.

set - A set of values or assets.
expression - Any expression.

First(set)

Takes the first item in a set.

set - A set of values or assets.

Last(set)

Takes the last item in a set.

set - A set of values or assets.

Item(set, position)

Takes the n-th item in a set.

set - A set of values or assets.
position - Position of the desired item.

List(set, [conjunction = "and"])

Joins a set of values together using commas and a conjunction between the last two items.

set - A set of values.
conjunction - The word that is inserted between the last two items.

Join(set, [separator = ", "])

Joins a set of values together with a separator between each item.

set - A set of values.
separator - Separator between each item.

Lines(set)

Joins a set of values together with each item on a separate line.

set - A set of values.

Paragraphs(set)

Joins a set of values together with each item in a separate paragraph.

set - A set of values.

Count(set)

Counts the number of items (including empty values) in a set.

set - A set of values or assets.

CountNotEmpty(set)

Counts the number of non-empty values in a set.

set - A set of values or assets.

Contact Functions

These functions operate on contact assets.

SubjectivePronoun(contact)

Gets the subjective pronoun (he/she/they) for one or more contacts.

contact - Contact.

ObjectivePronoun(contact)

Gets the objective pronoun (him/her/them) for one or more contacts.

contact - Contact.

PossessivePronoun(contact)

Gets the subjective pronoun (his/her/their) for one or more contacts.

contact - Contact.

Telephone Functions

These functions operate on telephone/fax numbers.

Telephone(phone, [format])

Formats a telephone number.

phone - Telephone number.
format - Format (Extension, Local, Domestic or International).

Tag Functions

These functions operate on tags.

HasTag(item, tag)

Determines whether an item has a particular tag (yes/no).

item - A taggable item (e.g. contact).
tag - Name of the tag.

Special Purpose Functions

Resource(type, id)

Creates a reference to a subscriber-specific resource in ContactsLaw.

type - Resource type.
id - Resource identifier.