2c6523a372
* add floor() and ceil() functions to simplexpr, akin to round() * document addition of floor() and ceil() * remove unnecessary second argument for floor() and ceil() * Update documentation --------- Co-authored-by: Martin Bogdanov <github () martinbogdanov.com>
72 lines
4.5 KiB
Markdown
72 lines
4.5 KiB
Markdown
# 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
|
|
|
|
```lisp
|
|
(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 (`=~`)
|
|
- Rust regex style, left hand is regex, right hand is string
|
|
- ex: workspace.name =~ '^special:.+$'
|
|
- 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 an empty string or a JSON `null`, then return `null`. Otherwise,
|
|
attempt to index. Note that indexing an empty JSON string (`'""'`) is an error.
|
|
- This can still cause an error to occur if the left hand side exists but is
|
|
not an object or an array.
|
|
(`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
|
|
- `floor(number)`: Round a number up to the nearest integer
|
|
- `ceil(number)`: Round a number down to the nearest integer
|
|
- `sin(number)`, `cos(number)`, `tan(number)`, `cot(number)`: Calculate the trigonometric value of a given number in **radians**
|
|
- `min(a, b)`, `max(a, b)`: Get the smaller or bigger number out of two given numbers
|
|
- `powi(num, n)`, `powf(num, n)`: Raise number `num` to power `n`. `powi` expects `n` to be of type `i32`
|
|
- `log(num, n)`: Calculate the base `n` logarithm of `num`. `num`, `n` and return type are `f64`
|
|
- `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](https://jqlang.github.io/jq/manual/) style command on a json value. (Uses [jaq](https://crates.io/crates/jaq) internally).
|
|
- `jq(value, jq_filter_string, args)`: Emulate command line flags for jq, see [the docs](https://jqlang.github.io/jq/manual/#invoking-jq) on invoking jq for details. Invalid flags are silently ignored.
|
|
Currently supported flags:
|
|
- `"r"`: If the result is a string, it won't be formatted as a JSON string. The equivalent jq flag is `--raw-output`.
|
|
- `get_env(string)`: Gets the specified enviroment variable
|
|
- `formattime(unix_timestamp, format_str, timezone)`: Gets the time in a given format from UNIX timestamp.
|
|
Check [chrono's documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) for more
|
|
information about format string and [chrono-tz's documentation](https://docs.rs/chrono-tz/latest/chrono_tz/enum.Tz.html)
|
|
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](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) for more
|
|
information about format string.
|