Simple expression language

Yuck includes a small expression language that can be used to run several operations on your data. This can be used to show different values depending on certain conditions, do mathematic operations, and even access values within JSON-structures.

These expressions can be placed anywhere within your configuration inside { ... }, as well as within strings, inside string-interpolation blocks ("foo ${ ... } bar").

Example

(box
  "Some math: ${12 + foo * 10}"
  (button :class {button_active ? "active" : "inactive"}
          :onclick "toggle_thing"
    {button_active ? "disable" : "enable"}))

Features

Supported currently are the following features:

  • simple mathematical operations (+, -, *, /, %)
  • comparisons (==, !=, >, <, <=, >=)
  • boolean operations (||, &&, !)
  • regex match operator (=~)
  • elvis operator (?:)
    • if the left side is "" or a JSON null, then returns the right side, otherwise evaluates to the left side.
  • Safe Access operator (?.) or (?.[index])
    • if the left side is "" or a JSON null, then return null. Otherwise, attempt to index.
    • This can still cause an error to occur if the left hand side exists but is not an object. (Number or String).
  • conditionals (condition ? 'value' : 'other value')
  • numbers, strings, booleans and variable references (12, 'hi', true, some_variable)
  • json access (object.field, array[12], object["field"])
    • for this, the object/array value needs to refer to a variable that contains a valid json string.
  • some function calls:
    • round(number, decimal_digits): Round a number to the given amount of decimals
    • sin(number), cos(number), tan(number), cot(number): Calculate the trigonometric value of a given number in radians
    • degtorad(number): Converts a number from degrees to radians
    • radtodeg(number): Converts a number from radians to degrees
    • replace(string, regex, replacement): Replace matches of a given regex in a string
    • search(string, regex): Search for a given regex in a string (returns array)
    • matches(string, regex): check if a given string matches a given regex (returns bool)
    • captures(string, regex): Get the captures of a given regex in a string (returns array)
    • strlength(value): Gets the length of the string
    • substring(string, start, length): Return a substring of given length starting at the given index
    • arraylength(value): Gets the length of the array
    • objectlength(value): Gets the amount of entries in the object
    • jq(value, jq_filter_string): run a jq style command on a json value. (Uses jaq internally).
    • formattime(unix_timestamp, format_str, timezone): Gets the time in a given format from UNIX timestamp. Check chrono's documentation for more information about format string and chrono-tz's documentation for available time zones.
    • formattime(unix_timestamp, format_str): Gets the time in a given format from UNIX timestamp. Same as other formattime, but does not accept timezone. Instead, it uses system's local timezone. Check chrono's documentation for more information about format string.