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 interger part of the result will be returned.