This “how to” article is to give some insights on using String Expressions and Functions with pimatic variable and rule definitions. For now, only the subString and date functions are covered. More content for other functions will be added soon.

String Expressions

String Expressions can be used for variables of type “Expression” and as parameters for some rule predicates and actions.
String Expressions may be one of the following:

  • variable references, e.g., $someVar
  • plain string, e.g., "ABC"
  • function calls, e.g., subString($someVar, "BB")
  • string with embedded expressions, "AA$someVar"

In some cases it is required to surround an embedded expression with curly brackets to get parsed properly, e.g. "{$someVar}BB". This way, it is also possible to embed function calls, e.g., "AA{subString($someText, "BB")}"

String Functions

subString() function

subString(<string: string expression>, <expression: regular expression>[, <flags: string>])

This function returns the substring of a given string expression matching the regular expression and flags where the latter may be provided optionally. The function uses Javascript regular expressions which are provided without the surrounding slashes and flags. Simply provide the regular expression as a string, e.g., "\D+". The flags may be optionally provided as a separate string.

Note, some special characters of regular expressions need to be escaped with a preceding backslash. Otherwise, they would be interpreted as pimatic special characters for string expressions or variable references. Use:

  • \{ and \} instead of { and } to specify occurrences of the preceding sub expression
  • \$ instead of $ to end of the string expression

In the following, some usage examples are provided which use a global variable $someVar set to the value "AABBCCC". If you wish to trial the example, define another global variable, e.g. $subText and set its type to “Expression”

  • subString($someVar, "BB") results in BB. It matches the first occurrence of the letter sequence BB in $someVar

  • subString($someVar, "B\{2\}") results in BB and is equivalent to expression above. Note, the curly braces need to be quoted with a backslash as the brace would be interpreted as an embedded pimatic expression otherwise

  • subString($someVar, "[A-Z]\{5\}") results in AABBC. Returns the first occurrence of five characters where each character is contained in the set “A to Z”

  • subString($someVar, "c", "gi") results in CCC. It concatenates all occurrences (flag g for global matching) of the letter c or C (flag i for case insensitive)

  • subString($someVar, "A|B", "g") results in AABB. It concatenates all occurrences (flag g for global matching) of the letters A or B

  • subString($someVar, ".\$") results in C. It matches the last character of $someVar. Note the dollar sign needs to be quoted with a backslash as the dollar sign would be interpreted variable reference start symbol, otherwise

  • Function calls can also be embedded into a string. To get it parsed properly the function is surrounded by brackets: "XX{subString($someVar, "..(..)")}" results in XXBB

  • It is also possible to nest function calls: subString(subString($someVar, "A|B", "g"), ".\$") results in B. The inner function yields all caracters A or B, i.e., AABB. The outer function yields the last character.

The following gives an example of using the function as part of a rule definition:

WHEN subString("$someVar", "A", "g") equals "AA"   
THEN toggle denon-avr-power

date() function

date([<format string: string>])

Outputs the current date using an optionally provided format string. If no format string is provided the format "YYYY-MM-DD hh:mm:ss" is used.
For the date formatting the date-format-lite package is used. See supported syntax below.

  • Y - A two digit representation of a year without leading zeros. Examples: 99 or 3
  • YY - A two digit representation of a year. Examples: 99 or 03
  • YYYY - A full numeric representation of a year, 4 digits. Examples: 1999 or 2003
  • M - Numeric representation of a month, without leading zeros. 1 through 12
  • MM - Numeric representation of a month, with leading zeros. 01 through 12
  • MMM - A short textual representation of a month, three letters. Jan through Dec
  • MMMM - A full textual representation of a month, such as January or March. January through December
  • D - Day of the month without leading zeros. 1 to 31
  • DD - Day of the month, 2 digits with leading zeros. 01 to 31
  • DDD - A textual representation of a day, three letters. Mon through Sun
  • DDDD - A full textual representation of the day of the week. Sunday through Saturday
  • H - 12-hour format of an hour without leading zeros. 1 through 12
  • HH - 12-hour format of an hour with leading zeros. 01 through 12
  • h - 24-hour format of an hour without leading zeros. 0 through 23
  • hh - 24-hour format of an hour with leading zeros. 00 through 23
  • m - Minutes without leading zeros. 0 through 59
  • mm - Minutes with leading zeros. 00 to 59
  • s - Seconds without leading zeros. 0 through 59
  • ss - Seconds with leading zeros. 00 to 59
  • S - Milliseconds without leading zeros. 0 through 999
  • SS - Milliseconds with leading zeros. 000 to 999
  • U - Milliseconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
  • u - Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
  • A - Ante meridiem and Post meridiem. AM or PM
  • "text" - text, quotes should be escaped, eg ‘“a \“quoted text\”” YYYY’

Time zone designators

  • Z - Time offsets from UTC in the form ±hh[:mm] Examples: +02, +02:30
  • ZZ - Time offsets from UTC in the form ±hh[mm] Examples: +02, +0230
  • ZZZ - Time offsets from UTC in the form ±hh:mm Examples: +02:00, +02:30
  • ZZZZ - Time offsets from UTC in the form ±hhmm Examples: +0200, +0230

ISO-8601

  • w - Day of the week. 1 (for Monday) through 7 (for Sunday)
  • W - Week number of year, first week is the week with 4 January in it
  • o - ISO-8601 year number. This has the same value as YYYY,
    except that if the ISO week number (W) belongs to the previous or next year, that year is used instead
  • iso - Full ISO-8601 date time string Example: 2013-07-10T13:47:36Z

hexString() function

hexString(<number: numeric expression>[, <padding: numeric expression>[, <prefix: string>]])

Converts a given number expression to a hex string.
Input parameters:

  • number: numeric expression: The number to be converted. Negative numbers will be treated as 32-bit signed integers. Thus, numbers smaller than -2147483648 will be cut off which> is due to limitation of using bitwise operators in JavaScript. Positive integers will be handled up to 53-bit as JavaScript uses IEEE 754 double-precision floating point numbers, internally.
  • padding: numeric expression: Specifies the (minimum) number of digits the resulting string shall contain. The string will be padded by prepending leading “0” digits, accordingly. By default, padding is set to 0 which means no padding is performed
  • prefix: string: Specifies a prefix string which will be prepended to the resulting hex number. By default, no prefix is set