Expression Syntax
Expressions are used in a several places in Carmenta Engine to calculate a value based on an attribute set. For example, all visualizers have a condition property with an expression; if the expression is evaluated to true given the attributes of the current feature, the visualizer is applied to that feature.
Expressions are specified as strings, and may contain simple numbers, strings etc., references to attributes in an attribute set, and arithmetic, relational and logical operators. They can also be nested to arbitrary depth using parentheses.
An expression is always evaluated in the context of an attribute set, typically from the current feature in an operator chain or the update attributes supplied from the view. Evaluating an expression always yields a result. The result will be an integer, double, bool, string or atom value (this is the same set of types that can be used in an AttributeSet) or the special value null.
Simple expressions
Literals
Literals are one of the following:
Integer numbers, for example 1 or -10000.
Floating point numbers, for example 2.5 or 6.02e23. Always use the point character '.' as the decimal separator.
Strings enclosed in double quotes, for example "A string literal". To include a double quote or a backslash in the string, prefix with a backslash: "\"A quoted string with a backslash \\\"". To include a line break in the Carmenta Studio expression editor, press Enter and continue writing the expression. If writing an expression string using the API you can add the character '\n' to insert the line break.
Interpolated strings provide a way of constructing strings by writing the text of the string plus expressions that fill in placeholders in the string. An interpolated string looks like a normal string except that it is prefixed with a dollar sign, for example $"An interpolated string". See the section on interpolated strings further down for more information.
Atoms, expressed using hash marks, for example #myAtom.
The constant values true, false or null.
Variables
Variables can be used to reference attributes in the attribute set used during evaluation. Variables are specified using just the name of the attribute. When evaluated, the attribute will be looked up in the attribute set and its value will be the value of the variable. If the attribute is not found in the attribute set, the value of the variable is null.
To access an attribute this way, the name may only contain uppercase and lowercase letters, digits and underscores. Also, the expression keywords 'null', 'true', 'false', 'if', 'then', 'else', 'and', 'or' and 'not' are not allowed. To access attributes with other characters in the name, or with names matching one of the keywords, use the attribute() function described below.
Complex expressions
Simple expressions can be combined using operators or built-in functions, to form more complex expressions. All the common arithmetic, relational and logical (written as and, or, not) operators are available and work as expected. Parentheses may be used to group sub-expressions. There is also a special if-then-else operator, and a possibility to convert sub-expressions between different types or call a few built-in functions.
Operators
Available operators, in order of precedence:
Operators | Description |
|---|---|
*, /, % | Multiplication, division, modulo. Can be used with sub-expressions of types integer and/or double numbers (see note below). |
+, - | Addition, subtraction. Can be used with integer and double sub-expressions. The addition operator can also be used to concatenate strings. |
=, !=, <, <=, >, >= | Compares two sub-expressions and yields a bool. |
expr1 in (expr2, expr3, exprn) | Returns true the value of expr1 equals any of the expressions in the list, false otherwise. |
not | Negates a bool expression. Negating null returns true. |
and, or | Returns true if both of, or at least one of, the two sub-expressions are true. |
if expr1 then expr2 else expr3 | Returns the value of expr2 or expr3, depending on if expr1 evaluates to true or not. |
expr1 , expr2 | If the value of expr1 interpreted as a bool is true, then the value expr1 is returned, otherwise the value of expr2. This is just shorthand for writing 'if expr1 then expr1 else expr2'. |
As in C and C++, the division operator performs integer division (rounding towards zero) if both operands are integers. For example, 10/4 evaluates to 2. If you want to do a floating point division on two integers, you must use a type conversion (see next section) on at least one of the integers. For example, double(10)/4 evaluates to 2.5.
Type conversions
The result of evaluating a sub-expression may be converted to another type. For instance, numbers may be converted to strings, and strings may be converted to numbers. In a few cases, the value will automatically be converted to the correct type. For instance, if you try to add an integer and a double, the integer will be automatically converted to a double before the addition. But sometimes you need to explicitly change the type of a sub-expression, using one of the following type casts:
Conversion | Applies to | Description |
|---|---|---|
int(expr) | Integers, doubles, bools, strings | Double numbers will be rounded to the nearest integer. Bools will be converted to 0 or 1. |
double(expr) | Integers, doubles, bools, strings | Bools will be converted to 0.0 or 1.0. |
bool(expr) | Integers, doubles, bools, strings | Numbers not equal to zero and any non-empty string will be converted to true; all other values to false. |
string(expr) | All | Integers and doubles will be formatted as strings. Atoms will be converted to the strings they represent. Bools will be converted to "false" or "true". |
atom(expr) | Strings, atoms | Strings will be converted to corresponding atoms. |
All other type conversions will fail, and return null.
Built-in functions
There are also a number of built-in functions you may use in an expression.
Function | Description |
|---|---|
abs(val) | Returns the absolute value of val. null is returned if argument is not a number. |
acos(val) | Returns the arccosine of val. null is returned if argument is not a number, or outside the range -1 to 1. |
asin(val) | Returns the arcsine of val. null is returned if argument is not a number, or outside the range -1 to 1. |
atan2(valy, valx) | Returns the arctangent of valy / valx, same as C library function atan2(). null is returned if any argument is not a number. |
attribute(name) | Returns the value of an attribute in the attribute set. The name of the attribute to return is determined by name, which must evaluate to a string or an atom. If name is not a string or atom, or if the attribute is not found, null is returned. |
contains(str1, str2, casesensitive) | Similar to the like function, but interprets the first string as a list of comma-separated strings. The substrings are extracted and leading and trailing whitespace is removed. Each substring is then tested against the wildcard string in the second parameter. Again, the third parameter specifies if the comparison should be case-sensitive or not, and may be omitted. The function returns true if any test is true, and false otherwise. |
cos(val) | Returns the cosine of val. null is returned if argument is not a number. |
deg2rad(val) | Converts val from degrees to radians. null is returned if argument is not a number. |
exp(val) | Returns the base-e exponential function of val. null is returned if argument is not a number. |
format(val, formatSpecifier) |
Converts val to a string according to formatSpecifier, see
Format specifiers for more information. null will
be converted to an empty string. If you do not supply a format specifier then
val will be converted to a string in the same way as if converted by the
string() function, except that as noted earlier null will result in an
empty string. |
length(str) | Returns the length of str, which must be a string. |
like(str1, str2, casesensitive) | Compares two strings using wildcards. The second string may contain '*' characters (matching any sequence of zero or more characters in the first string) or '?' characters (matching exactly one character in the first string). The third parameter is interpreted as a bool, and specifies if the string comparison should be case-sensitive or not. It may be omitted and if so performs a case-sensitive comparison. |
log(val) | Returns the natural logarithm of val. null is returned if argument is not a number, or less than or equal to zero. |
lowercase(str) | Returns a copy of str converted to lowercase. |
max(val1, val2) | Returns the largest value of val1 and val2. null is returned if any argument is not a number. |
min(val1, val2) | Returns the smallest value of val1 and val2. null is returned if any argument is not a number. |
rad2deg(val) | Converts val from radians to degrees. null is returned if argument is not a number. |
rand() | Returns a pseudorandom double number between 0.0 and 1.0. |
sin(val) | Returns the sine of val. null is returned if argument is not a number. |
sqrt(val) | Returns the square root of val. null is returned if argument is not a number, or negative. |
substr(str, start, count) | Extracts a substring from str, which must be a string. start and count specifies the start position of the substring within str, and the number of characters to extract. count may be omitted, in which case the rest of the string is extracted. |
tan(val) | Returns the tangent of val. null is returned if argument is not a number. |
titlecase(str) | Splits str into words, capitalizes each word (the first character is capitalized and the rest lowercased) and finally joins the words into a single string. Any leading or trailing whitespace is removed and runs of whitespace characters between words is replaced by a single space character. |
uppercase(str) | Returns a copy of str converted to uppercase. |
In addition, the following built-in functions are available in expressions used when searching for Catalog metadata documents with the CatalogQuery class:
Function | Description |
|---|---|
keyword(name, thesaurus, casesensitive) | Returns true if the metadata document is tagged with the keyword name from the thesaurus thesaurus. If thesaurus is an empty string, only keywords without a thesaurus specification are searched. If thesaurus is null or omitted, all keywords regardless of thesauri are searched. The third parameter, if specified, indicates if the search is case-sensitive or not; default is false. |
boundingbox(west, south, east, north) | Returns true if the extent specified in a metadata document overlaps the bounding box specified by the west, south, east and north parameters. |
Interpolated strings
An interpolated string is a special kind of string literal that contains placeholders that are evaluated and replaced at runtime. To indicate that a string is an interpolated string you prefix it with a dollar sign. For example:
$"An interpolated string"
Placeholders in an interpolated string are expressions in side a pair of braces:
$"An interpolated string with a placeholder: {1 + 2}"
What makes interpolated string really useful is when the placeholders contain expressions that use values from the context, the set of attributes, that the evaluation is performed in. The following interpolated string composes a string from the NAME and POPULATION attributes:
$"City: {NAME}, Population: {POPULATION}"
If this string is evaluated in a context where NAME is New York and POPULATION is 8.4 million then the result is the string:
"City: New York, Population: 8.4 million"
Placeholder expressions that evaluate to null at runtime, for example if an attribute is missing, will result in an empty string. This means that if POPULATION is missing the result will become:
"City: New York, Population: "
To continue with this example, the result above looks a bit strange when it just ends without a population specified so how can we improve this? Well, a placeholder expression is an expression, this means that the interpolated string could have been written:
$"City: {NAME}, Population: {POPULATION,\"NA\"}"
Now the population uses the shorthand version of an if-then-else expression to show NA when the POPULATION attribute is missing. Note that we had to escape the quote characters around NA since they are contained in a string (the interpolated string). In the same way, we would have to escape brace characters if we want them in the result since they are used to delimit placeholder expressions inside the interpolated string.
A placeholder expression can also include a format specifier that specify formatting options for the expression:
$"Some string: {STRING:tc} Some value: {VALUE:f2}"
This interpolated string used the tc format specifier, which converts a string to title-case (each word is capitalized), and f2 which formats a number as a fixed-point number with two decimals. The next section describes all format specifiers you can use.
Format specifiers
The following table lists the available format specifiers that can be used in an interpolated string or when calling the built-in format() function.
Format specifier | Description |
|---|---|
d or D |
Result: Formatted as an integer. |
f or F |
Result: Formatted as a fixed-point number. |
e or E |
Result: Formatted using scientific notation. |
lc or LC |
Result: A string with all characters converted to lowercase. |
uc or UC |
Result: A string with all characters converted to uppercase. |
tc or TC |
Result: A string with all in which all words have been capitalized. |
Not supplying a format specifier has the same meaning as converting a value to a string using the built-in string() function except that a null value will be converted to an empty string. In other words, the following expressions are equivalent:
$"{VALUE}"
format(VALUE)
string((VALUE, ""))
if VALUE then string(VALUE) else ""
Error handling and the null expression
If an expression can't be parsed, e.g. due to syntax errors in the expression, Carmenta Engine throws an exception. This is usually done when the application loads its Carmenta Engine configuration file. But once the expression is correctly parsed, it will never generate any errors or exceptions. Instead, if something goes wrong during evaluation, the special value null is returned. This could be due to missing attributes, or division by zero. null is also returned if you call a function with incorrect parameters or apply an operator to values of incorrect types.
Usually, if a sub-expression returns null, the whole expression will return null, since the operators and functions will return null if any operand/argument is null. You can handle these errors, simply by comparing the value of the sub-expressions to null. The following example shows how to check for the existence of an attribute, and use a default value if it is missing:
if MyAttr != null then MyAttr else "Default"
Unlike most other expressions, a relational expression will return true or false even if an operand is null. In comparisons, null is regarded as the smallest of all values. For example, if alpha is an attribute that is not defined, then the expression alpha > 42 will evaluate to false, but alpha < 42 will evaluate to true (since alpha would evaluate to null).
null is also handled differently by the built-in format() function and when expressions inside interpolated strings are evaluated. In both cases, the result of the function call and the evaluation of the expression inside the interpolated string, will be an empty string.