Expression

From ContactsLaw Documentation
Revision as of 14:28, 5 December 2023 by Bradley Smith (talk | contribs)

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 the above (e.g. Contact.ShortName).

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.

Function Reference

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)

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

  • set - A set of values.
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.

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. 

IsEmpty(value)

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

IsNotEmpty(value)

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

AllEmpty(value)

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

AllNotEmpty(value)

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

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

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

DefaultIfMultiple(value, default)

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

Not(condition)

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

Contains(set, value)

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

Intersects(set1, set2)

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

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

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

When(value, result)

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

Else(value)

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

Telephone Functions

Telephone(phone, [format])

Formats a telephone number.

Date and Time Functions

Date(date, format)

Formats a date as text. 

AddMinutes(date, minutes)

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

AddHours(date, hours)

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

AddDays(date, days)

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

AddWeekDays(date, days)

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

AddMonths(date, months)

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

AddYears(date, years)

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

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

Sets the time component of a date/time value. 

SetTimeZone(date, tz)

Changes the time zone of a date/time value. 

Day(date)

Gets the day component of a date/time value. 

Month(date)

Gets the month component of a date/time value. 

Year(date)

Gets the year component of a date/time value. 

Hour(date)

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

Minute(date)

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

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. 

Minutes(date1, date2)

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

Years(date1, date2)

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

Age(date)

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

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

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

HoursAndMinutes(minutes)

Expresses a quantity of minutes in hours and minutes.

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.

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.

Special Purpose Functions

Resource(type, id)

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

  • type - Resource type.
  • id - Resource identifier.
Retrieved from "https://docs.contactslaw.com.au/index.php?title=Expression&oldid=237"