Expressions

Owned by Samo Jurdik
Last updated: Nov 25, 2024 by Martin Kalis
15 min read

Multi-line scripting language with syntax highlighting, usable in smart rules Equation, Formula and Script, and also in Modbus and Packet parser interfaces.

800

Basics

Association

Mu := Se + 2;

Multi-line algorithm

Each line is divided by semicolon

Last := Current; Current := 0;

Returned value

  • Result of last line of code

  • RETURN(expression) stops execution of algorighm and returns content inside brackets

(Co2 > 800) AND (Wind < 10); equals: RETURN((CO2 > 800) and (Wind < 10));

Temporary variable

Lives within the single execution of the script.

IF clause

Excel style

Multi-line style

Switch

doc_tap_TestsExprAgainst;

Example:

Loop

LOOP / WHILE ... repeats a series of commands based on a specified condition until that condition is met.
CONTINUE ... skips the execution of commands and continues to the next cycle.
BREAK ... terminates the loop.

Example with condition at the beginning:

Example with condition at the end:

NaN (not a number) value

NaN can be returned as a value in case real value is not known.

ISNAN(expression) function
Returns TRUE if expression is not a number.

ISNULL

Returns true if the parameter is NULL, false otherwise. Used for String and Bytearray types. Example: if XML element is not found, returned value ISNULL.

The syntax of the function is:

Sleep

Sleeps the script for number of miliseconds. Use only in very specific cases.

Comments

New line starting with character #

Numeric literals

doc_tap_HexaNo;

doc_tap_Expr_HexNo;

0x0A = 10

Binary numbers

0b1010 = 10

doc_tap_MathsExp;

+, -, *, /

doc_tap_Logic_Exp;

AND, OR, !, =, !=, >, <

doc_tap_Funkcie;

LINEAR

doc_tap_linearHodnota;

doc_tap_expressions_linear_examples_bounds;

Examples

doc_tap_expressions_linear_parameters;

HYSTERESIS

Hysteresis can be used to filter signals so that the output reacts less rapidly than it otherwise would by taking recent system history into account. For example, a thermostat controlling a heater may switch the heater on when the temperature drops below A, but not turn it off until the temperature rises above B.

Returns 0 or 1.

Example: maintain a temperature of 20 °C within 2 ºC hysteresis range. Turn the heater on when the temperature drops to below 18 °C and off when the temperature exceeds 22 °C).

doc_tap_MathematicalOperations;

MIN

doc_tap_return_mensiu;

Examples:

MINSTRICT

doc_tap_return_mensiu_strict;

Examples:

MAX

doc_tap_return_vacsiu;

Examples:

MAXSTRICT

doc_tap_return_vacsiu_strict;

Examples:

AVG

doc_tap_avg_function;

Examples:

AVGSTRICT

doc_tap_avgstrict_function;

Examples:

ROUND

doc_tap_return_round;

ABS

The ABS function returns the absolute value (i.e. the modulus) of any supplied number.

Examples:

DEWPOINT

POWER

The POWER function calculates a given number, raised to a supplied power.

Examples:

  • POWER(2,3) … 2^3 = 8

  • POWER(10, -3) … 0,001

  • POWER(25, 0) … 1

MOD

The MOD function returns the remainder of a division between two supplied numbers.

Arguments:

  • number - The number to be divided.

  • divisor - The value that the number argument is divided by.

Examples:

  • MOD(6, 4)  … 2

  • MOD(6, 2.5) … 1

CEIL

The CEIL function rounds a supplied number away from zero, to the nearest multiple of a given number.

Arguments:

  • number   - The number that is to be rounded.

  • significance (optional) - The multiple of significance that the supplied number should be rounded to. If the significance is not specified, then it is equal to 1.
    (This should generally have the same arithmetic sign (positive or negative) as the supplied number argument)

Examples:

  • CEIL(22.25,0.1) … 22.3

  • CEIL(22.25,1) … 23

  • CEIL(22.25) … 23

  • CEIL(-22.25,-1) … -23

  • CEIL(-22.25,1) … -22

  • CEIL(-22.25) … -22

  • CEIL(-22.25,-5) … -25

FLOOR

The FLOOR function rounds a supplied number towards zero to the nearest multiple of a specified significance.

Arguments:

  • number - The number that is to be rounded.

  • significance (optional) -The multiple of significance that the supplied number is to be rounded to. If the significance is not specified, then it is equal to 1.
    (This should generally have the same arithmetic sign (positive or negative) as the supplied number argument)

Examples:

  • FLOOR(22.25,0.1)… 22.2

  • FLOOR(22.25,1) … 22

  • FLOOR(22.25) … 22

  • FLOOR(-22.25,-1) … -22

  • FLOOR(-22.25,1) … -23

  • FLOOR(-22.25) … -23

  • FLOOR(-22.25,-5) … -20

RAND

The Rand function generates a random real number between 0 and 1.

Examples:

  • RAND()

RANDINT

The RANDINT function generates a random integer between two supplied integers.

Examples:

  • RANDINT(1,5)

  • RANDINT(-2,2)

SIGN

The SIGN function returns the arithmetic sign (+1, -1 or 0) of a supplied number. I.e. if the number is positive, the SIGN function returns +1, if the number is negative, the function returns -1 and if the number is 0 (zero), the function returns 0.

Examples:

  • SIGN(100) … 1

  • SIGN(0) … 0

  • SIGN(-100) … -1

SQRT

The SQRT function calculates the positive square root of a supplied number.

Examples:

  • SQRT(25) … 5

LOG

The LOG function calculates the logarithm of a given number, to a supplied base.

Arguments:

  • number - The positive real number that you want to calculate the logarithm of.

  • base (optional) - An optional argument that specifies the base to which the logarithm should be calculated.
    If the argument is not specified, then the base argument uses the default value 10.

Examples:

  • LOG(4,0.5) … -2

  • LOG(100) … 2

LN

The LN function calculates the natural logarithm of a given number.

where the number argument is the positive real number that you want to calculate the natural logarithm of.

Examples:

  • LN(100) … 4,60517

doc_tap_BitOp;

GETBIT

Returns a value of a bit in the specified position.

Arguments:

  • number - number to extract value of specific bit from

  • bit_position - position of bit, starting with 0, from right

Examples:

  • GETBIT(2, 0) → first bit of number 2 (0b0010) is 0

  • GETBIT(4,2) → third bit of number 4 (0b0100) is 1

GETBITS

Returns value of specified number of bits in the specified position.

Examples:

  • GETBITS(216, 3, 2) → number 216 = 0b1101 1000; value of 4th bit from the right is 1, 5th bit is 1, therefore result is 0b0011 = 3

  • GETBITS(0xFF, 0, 4) → number 0xFF = 255 = 0b1111 1111; value of first 4 bits from right is 0b1111 = 0xF = 15

GETBYTE

Returns a value of a byte in the specified number.

Arguments:

  • number - number to extract value of specific byte from

  • byte_position - position of byte, starting from 0, from right

Examples:

SETBYTE

Assigns a new value to the specified byte in the provided number, and returns assigned value.

Examples:

SETBIT

Assigns a new value to the specified bit in the provided number and returns a new number.

Arguments:

  • number - number to be modified

  • bit_position - position of bit, starting with 0, from right

  • new_value - 0 or 1 - value that is going to be set to specified bit

Examples:

  • SETBIT(1, 1, 1) → 3

  • SETBIT(3, 1, 1) → 3

  • SETBIT(4, 2, 0) → 4

  • SETBIT(12, 1, 0) → 14

SETBITS

Assigns a new value to the specified bits in the provided number and returns a new number.

Examples:

  • SETBITS(192, 4, 2, 3) → 240

  • SETBITS(192, 5, 2, 3) → 224

<<   (LEFT BIT SHIFT)

Excel: BITLSHIFT(number, shift_amount)

>> (RIGHT BIT SHIFT)

Excel: BITRSHIFT(number, shift_amount)

& (BITWISE AND)

Excel: BITAND(number1, number2)

| (BITWISE OR)

Excel: BITOR(number1, number2)

See the example of bit operations in Google Sheets:
https://docs.google.com/spreadsheets/d/1hF5FMpGMJbgYh-YLwWrq2n186_ATyGyLUb689__IhLY/edit?usp=sharing

Or try interactive tool at http://bitwisecmd.com/

Text, String and Byte array

LENGTH

Returns length of an object or number of bytes. Object can be a number, boolean, string or Collection.

Examples:

BYTECOLLECTION

Creates a Collection<UInt8> from specified hexadecimal values

Examples:

INDEXOF

Returns index of specified element in string or collection. Returns -1 if element cannot be found.

Examples:

COPY

Copies specified string or collection (or part of them)

Examples:

REPLACE

Returns a new string or collection, in which all occurrences of specified value are replaced with new value.

Examples:

SPLIT

Splits string to substrings based on separator parameters.

Examples:

COMPARE

Compare 2 strings and returns an integer that indicates their relative position in the sort order.

Examples:

APPEND

Append value to collection or string and returns new object with appended value.

Examples:

INSERT

Insert value to collection or string. Returns collection or string with inserted value.

Examples:

REMOVEAT

Remove elements from collection or string based on element index and length. Returns collection or string without specified elements.

Examples:

GETAT

Get element value from collection or string based on provided index.

Examples:

SETAT

Set element value in collection or string at provided index.

Examples:

ENCODE

Encodes specified string using on of the formats and returns the new string.

Supported formats:

  • XML

  • Base64

Examples:

DECODE

Decodes specified string using one of the formats and returns the new string.

Supported formats:

  • XML

  • Base64

Examples:

EQUALS

Compares two numbers with floating point. The numbers are considered to be equal if | n1 - n2 |< epsilon The default value of threshold (epsilon) is 0.005 and it is an optional parameter.

Examples:

Sorting

doc_tap_sorting_description;

ORDER

doc_tap_sorting_order;

Examples:

ORDERINDEX

doc_tap_sorting_orderindex;

Examples:

ORDERSTRICT

doc_tap_sorting_orderstrict;

Examples:

ORDERINDEXSTRICT

doc_tap_sorting_orderindexstrict;

Examples:

ORDERDESC

doc_tap_sorting_orderdesc;

Examples:

ORDERINDEXDESC

doc_tap_sorting_orderindexdesc;

Examples:

ORDERDESCSTRICT

doc_tap_sorting_orderdescstrict;

Examples:

ORDERINDEXDESCSTRICT

doc_tap_sorting_orderindexdescstrict;

Examples:

Date and time

DATETIME

doc_tap_sorting_datetime;

Examples:

NOW

doc_tap_sorting_now;

Examples:

TIMESPAN

doc_tap_sorting_timespan;

Examples:

LOCALTIMEZONE

doc_tap_sorting_localtimezone;

Examples:

DATETIMEADD

doc_tap_sorting_datetimeadd;

Examples:

Data type conversions

TODOUBLE

doc_tap_sorting_todouble;

Examples:

TOSTRING

doc_tap_tostring_description;

Examples:

TOBCD

Converts the provided number to the binary-coded decimal (BCD) format. The scheme of encoding is BCD-8421.

Examples:

FROMBCD

Decodes the provided number, that is encoded in binary-coded decimal (BCD) format. The scheme of encoding is BCD-8421.

Examples:

TOBYTEARRAY

Converts string to byte array according to the specified encoding. Encoding is optional (iso-8859-1 is used by default).

Examples:

RGBTOHSV

Converts RGB color definition; returns color in Hue / Saturation / Brightness format.

Example:

HSVTORGB

Converts color defined by Hue / Saturation / Brightness; returns color in RGB format

Example:

Parsing functions

PARSETEXT

Returns part of input text, based on left and right search patterns

Examples:

PARSEJSON

Returns value of element from json formatted string. Element is specified with json path.

Examples:

PARSEXML

Returns value of element from xml string. Element is specified with xml path.

Examples:

If xml contains namespaces, you have to fully specify element names with namespace, eg. PARSEXML(xml, "//DIDL-Lite:container[dc:title='My Playlist’']/DIDL-Lite:res");

Packet parser

doc_tap_script_moreinfo_pp;

SENDHTTPREQUEST

SENDDATA

MQTTPUBLISH

FTPDOWNLOAD

FTPUPLOAD

COMPLETESERVICEATTRIBUTE

COMPLETESERVICEACTION

Modbus

Modbus

doc_tap_follow_link_Modbus;