Expressions

Introduction

An expression is a complex mathematical construction built using operands and operators. The simplest of expressions can have one operand, returning its value: 6 or $now. Generally, expressions contain multiple operands separated by operators. The operands represent the values, while the operators provide the operations to be performed on these values. Here's a simple example of a two-operand expression: 6 + 4. In this example, there are two operands, 6 and 4 and one operator, +, the mathematical addition operator. The result of this expression is obviously 10.

Using an expression

When building a webCoRE piston, there are several ways values can be provided within piston operands. The operand type selection allows for several types, among which the Value and the Expression types. When a Value type is selected, a Value field is displayed right next to the operand type selector. When an Expression type is selected, an Expression field is displayed underneath the selector and provides multiple line editing and autocomplete suggestions. Expressions can be used directly in an Expression field, but they can also be embedded into Value fields, by using the curly brackets {<expression>}. This allows for quick use of expressions while building, say, an output string:

The sum of 6 and 4 is {6 + 4}

webCoRE will parse anything that is between curly brackets as expressions and handle them as such.

Values versus Expressions

Which one you end up using is really a matter of choice, they can both do the same exact thing, although they differ from each-other. A Value field is an output-driven field, meaning it makes it easy to build output strings that need to be displayed in logs, notifications, etc. Think of a Value field like an Expression field that has implied double quotes (") at the start and end. In reverse, an Expression field is similar to a Value field that has curly brackets around it. Here's an example:

We can convert this Value field : The sum of 6 and 4 is {6 + 4} into an Expression field by simply placing double quotes around it: "The sum of 6 and 4 is {6 + 4}"

We can convert this Expression field : "The sum of 6 and 4 is " + (6 + 4) into a Value field by simply placing curly brackets around it: {"The sum of 6 and 4 is " + (6 + 4)}

All four examples above are equivalent and will output the same result: The sum of 6 and 4 is 10

Expression operands

Expression operands come in different types:

Literal strings

contain strings, pieces of text that will be output as-is, like that "The sum of 6 and 4 is " above

Numeric values

anything like integer numbers or decimal numbers: 6 or 2.4

Variables

the name of any defined variable, local, system, or global, can be simply written and the expression will know to replace that with its actual value, for example $now

Functions

webCoRE allows functions in expressions, these can help convert values around and extend the power of expressions, for example dewPoint(77, 80), or round(6.24)

Device attributes

use the special construction [name:attribute] or [variable:attribute] to include the attribute value of that device.

Devices

use the special construction [name] or [variable] to point to a device. This is not a device attribute, but the device itself and when converted to string will give the device's name

Expression operators

webCoRE supports over 20 operators, with various meanings. Operators generally sit in between two operands and determines the operation that is performed on the two. When only one operand exists, the other may be automatically implied, as described below. Another important factor is the order of operations, also explained below.

For each of the operators explained below, we are assuming we have two operands around it, a operator b. For simplicity, we will be referring to the two operands simply as a and b.

Addition (a + b)

Performs the mathematical addition of a plus b. If any of a or b is a string, concatenation is performed, so "test" + 1 will result in test1, while 6 + 4 will result in 10. If a and b are device-typed variables, the result will be a new list with all the devices present in either a or b.

Subtraction (a - b)

Performs the mathematical subtraction of a minus b. If a and a are device-typed variables, the result will be the list of devices in a, but excluding any devices that exist in b. Otherwise, both a and b will be evaluated as numbers and subtracted.

Multiplication (a * b)

Performs the mathematical multiplication of a times b. Both a and b will be evaluated as numbers and multiplied.

Division (a / b)

Performs the mathematical division of a divided by b. Both a and b will be evaluated as numbers and multiplied. If any of the two operands is a decimal, the result will be a decimal. If both operands are integers, the result will be an integer.

Integer division (a \ b)

Performs the mathematical division of a divided by b. Both a and b will be evaluated as numbers and divided, then the integer part of the result will be returned.

Modulo (a % b)

Performs the mathematical modulo operation of a modulo b. Both a and b will be evaluated as numbers and divided, then the remainder of the division will be returned.

Power (a ** b)

Performs the mathematical exponential operation of a at the power of b. Both a and b will be evaluated as numbers and divided, and ab will be returned.

Bitwise AND (a & b)

Performs the bitwise AND operation between a and b. Both a and b will be evaluated as integers and a bitwise AND will be applied between them. See Bitwise operators for more details.

Bitwise OR (a | b)

Performs the bitwise OR operation between a and b. Both a and b will be evaluated as integers and a bitwise OR will be applied between them. See Bitwise operators for more details.

Bitwise XOR (a ^ b)

Performs the bitwise OR operation between a and b. Both a and b will be evaluated as integers and a bitwise OR will be applied between them. See Bitwise operators for more details.

Bitwise NOT (~ b)

Performs the bitwise NOT operation on the immediately following operand. The operand will be evaluated as an integer and a bitwise NOT will be applied to it. See Bitwise operators for more details.

Logical AND (a && b)

Performs the logical AND operation between a and b. Both a and b will be evaluated as booleans and the result will be true only when both operands evaluate as true.

Logical OR (a || b)

Performs the logical OR operation between a and b. Both a and b will be evaluated as booleans and the result will be true when any of the two operands evaluate as true.

Logical XOR (a ^^ b)

Performs the logical XOR operation between a and b. Both a and b will be evaluated as booleans and the result will be true only when one of the two operands evaluates as true and the other one evaluates as false.

Logical negation (!b)

Performs the logical negation operation on the immediately following operand. The operand will be evaluated as boolean and the result will be true if the operand evaluates as false.

Logical double-negation (!!b)

Converts the immediately following operand into a boolean. The operand will be evaluated as boolean and returned as is.

Equality (a == b)

Returns true if a is equal to b. Depending on the operand data types, one or the other, or even both, may have to be converted to a common data type before comparison is performed.

Inequality (a != b)

Returns true if a is NOT equal to b. Depending on the operand data types, one or the other, or even both, may have to be converted to a common data type before comparison is performed. An alias of the inequality operator is <>

Less than (a < b)

Returns true if a is less than b. Depending on the operand data types, one or the other, or even both, may have to be converted to a common data type before comparison is performed. It can natively compare numbers and strings.

Less than or equal to (a <= b)

Returns true if a is less than or equal to b. Depending on the operand data types, one or the other, or even both, may have to be converted to a common data type before comparison is performed. It can natively compare numbers and strings.

Greater than (a > b)

Returns true if a is greater than b. Depending on the operand data types, one or the other, or even both, may have to be converted to a common data type before comparison is performed. It can natively compare numbers and strings.

Greater than or equal to (a >= b)

Returns true if a is greater than or equal to b. Depending on the operand data types, one or the other, or even both, may have to be converted to a common data type before comparison is performed. It can natively compare numbers and strings.

Parenthesis ( .. )

Not an operator per-se, parenthesis are used to group operands and operators together to alter the normal order of operations. For example, 6 + 4 * 2 returns 14, but if we really need to find the double of 6 + 4, then we write it like this (6 + 4) * 2. Parenthesis and curly brackets are interchangeable, you can use either or, but ensure you close them with the same style: {(6 + 4) * 2} ** 2

Ternary operator ( c ? t : f )

A great tool to simplifying expressions, the ternary operator evaluates c as a boolean, then if that evaluation is true, returns t, otherwise returns f.