References use a shell-like format: `${`reference-name`}`. Each reference is resolved to a data that is substitued to the reference at the corresponding place in the string. The `reference-name` can be composed of alphabetic characters, dashes (`'-'`) and underscores (`'_'`).

You can use an array-like syntax for some values: `${`reference-name`[`key`]}` (square brackets `[]` are literals here). The `key` can be a name or a number depending on the data pointed by `reference-name`. If `key` starts with a `@`, then the remaining is used as a join value. You can use fallback values, substitute values or regexes on array members. In case of joined values, such operations are done on the joined values as a whole.

You can use a fallback value if the data resolves to `nothing` or `false`. The syntax is: `${`reference-name`:-`fallback-value`}`.

You can use a substitute value if (and only if) the data resolves to `something` or `true`. The syntax is: `${`reference-name`:+`substitute-value`}`.

You can use a substitute value if (and only if) the data resolves to `nothing` or `false`. The syntax is: `${`reference-name`:!`substitute-value`}`.

You can use a switch substitute if the data resolves to `a boolean`. The syntax is: `${`reference-name`:{`separator` `value-if-false` `separator` `value-if-true`}}` (spaces added for readability only, they are not ignored when parsed).

You can use a range substitute if the data resolves to `a number`. The syntax is: `${`reference-name`:[`separator` `range-start` `separator` `range-end` `separator` `substitute-value`…]}` (spaces added for readability only, they are not ignored when parsed, the external square brackets `[]` are literals here).

You can use a prettify flag to make a big value more readable. The syntax is: `${`reference-name`(`flag``addition`)}`. The following flags are supported:

`f`

- Work on `a number`. It will display the value as a float, allowing for extra formatting, as with printf:

  Optionally, you can add a width (optionally with zero-padding): `0`width``

  Optionally, you can add a precision: `.`presicion``

`p`

`b`

- Work on `a number`. They will reduce the number to a minimum, adding the corresponding SI prefix (or binary prefix for `b`).

  You can use the same additions as flag `f`

`t`

- Work on `a number`. The number will be used as a UNIX timestamp.

  You can have an strftime-like format string as addition.

`d`

- Work on `a number`. The number will be used as seconds.

  You can have a nested format string as addition, with the following data available:

  - `%{weeks}`
  - `%{days}`
  - `%{hours}`
  - `%{minutes}`
  - `%{seconds}`
  - `%{milliseconds}`
  - `%{microseconds}`
  - `%{nanoseconds}`
  .

  The default format is `%{weeks:+%{weeks} week%{weeks:[;2;2;;s]} }%{days:+%{days} day%{days:[;2;2;;s]} }%{hours:+%{hours} hour%{hours:[;2;2;;s]} }%{minutes:+%{minutes} minute%{minutes:[;2;2;;s]} }%{seconds:-0} second%{seconds:[;2;2;;s]}`.

`j`

- Work on `a string`. The string will be escaped to be usable in a JSON string.

You can replace parts of the data using the regex mechanism. The syntax is: `${`reference-name`/`regex`/`replacement`}`. The `replacement` part is optional (including the preceding forward slash). If it is omitted, matching parts of the data will simply be removed. You can repeat the `/`regex`/`replacement`` part to replace as many patterns as you like. Each pattern is matched against the previous replacement so be careful in your order.

Examples (with data and resolved string):

`"${name} is eating a ${fruit}."`

- `name` is `"Bob"` and `fruit` is `"pear"`.

  Resolves to: `Bob is eating a pear.`

`"${name} is eating a ${fruit:-banana}."`

- `name` is `"Bob"` and `fruit` is `"pear"`.

  Resolves to: `Bob is eating a pear.`

`"${name} is eating a ${fruit:-banana}."`

- `name` is `"Bob"` and `fruit` is `nothing`.

  Resolves to: `Bob is eating a banana.`

`"${name} is eating a ${fruit}${addition:+ cooked with }${addition}."`

- `name` is `"Bob"`, `fruit` is `"pear"` and `addition` is `"chocolate"`.

  Resolves to: `Bob is eating a pear cooked with chocolate.`

`"${name} is eating a ${fruit}${addition:+ cooked with }${addition}."`

- `name` is `"Bob"`, `fruit` is `"pear"`and `addition` is `nothing`.

  Resolves to: `Bob is eating a pear.`

`"${name} is eating a ${addition:! raw }${fruit}."`

- `name` is `"Bob"`, `fruit` is `"pear"` and `addition` is `"chocolate"`.

  Resolves to: `Bob is eating a pear.`

`"${name} is eating a ${addition:! raw }${fruit}."`

- `name` is `"Bob"`, `fruit` is `"pear"`and `addition` is `nothing`.

  Resolves to: `Bob is eating a raw pear.`

`"${mode} mode is ${active:{;active;inactive}}."`

- `mode` is `"Random"` and `active` is `true`.

  Resolves to: `Random mode is active.`

`"${name} is eating a ${note:[;1;5;very bad;bad;good;very good]} ${fruit}."`

- `name` is `"Bob"`, `fruit` is `"apple"`and `note` is `5`.

  Resolves to: `Bob is eating a very good apple.`

`"Battery power: ${power(f03.1)}%."`

- `power` is `80.1`.

  Resolves to: `Battery power: 080.1%.`

`"Disk space: ${space(b)}B."`

- `space` is `1048576`.

  Resolves to: `Disk space: 1MiB.`

`"${time(t)}"`

- `time` is `1519910048`.

  Resolves to: `Thu Mar 1 14:14:08 2018`

`"${time(t%F %T)}"`

- `time` is `1519910048`.

  Resolves to: `2018-03-01 14:14:08`

`"${buildtime(d)}"`

- `buildtime` is `905`.

  Resolves to: `15 minutes 5 seconds`

`"${name} is eating a ${fruit}${addition/^/ cooked with }."`

- `name` is `"Bob"`, `fruit` is `"pear"` and `addition` is `"chocolate"`.

  Resolves to: `Bob is eating a pear cooked with chocolate.`

`"${name} is eating a ${fruit}${addition/^/ cooked with }."`

- `name` is `"Bob"`, `fruit` is `"pear"`and `addition` is `nothing`.

  Resolves to: `Bob is eating a pear.`

`"${name} is eating a ${fruit}${addition/^/ cooked with /$/ from Switzerland}."`

- `name` is `"Bob"`, `fruit` is `"pear"` and `addition` is `"chocolate"`.

  Resolves to: `Bob is eating a pear cooked with chocolate from Switzerland.`

## Colour strings

The `colour string` format is borrowed from the CSS4 Color values. Hexadecimal (`#`-prefixed), `rgb()` RGB(A), `hsl()` HSL(A), `hwb()` HWB and colour names notations are supported.

Here is a quick description:

`#`RR``GG``BB``AA``

`#`R``G``B``A``

- Each value is an `hexadecimal` value in the `0x00`-`0xff` range.

  The alpha value is an extension of the CSS3 notation and is optional.

  The single-letter version means duplicating the character (e.g. `"#123"` means `"#112233"`).

`rgb(`red`, `green`, `blue`)`

`rgba(`red`, `green`, `blue`, `alpha`)`

- Each colour value can be an `number` in the `0`-`255` range or a `percentage` value.

  The alpha value is a `floating point` or a `percentage` value.

`hsl(`hue`, `saturation`, `lightness`)`

`hsla(`hue`, `saturation`, `lightness`, `alpha`)`

- Hue is an `angle` either in `degrees` (unit `deg` or no unit), `gradians` (unit `grab`), `radians` (unit `rad`) or `turns` (unit `turn`, a `floating point number` from `0` to `1`).

  The saturation and lightness values are `percentage` values.

  The alpha value is the same as the `rgba()` notation.

`hwb(`hue`, `whiteness`, `blackness`, `alpha`)`

- Hue is the same as the `hsl()` notation.

  The whiteness and blackness values are `percentage` values.

  The alpha value is the same as the `rgba()` notation.

a CSS4-defined colour name

- One of the named colour from the CSS4 Color names list.

`transparent`

- Special colour treated as `rgba(0, 0, 0, 0)`.

## Binding strings

The `binding string` format supports two (and a half) notations. It can be either ``Modifier`-`Modifier`-`Bind`` or the GTK+ accelerator format.

The bind can either be a keysym name, a keycode in square brackets (e.g. `[10]`) or a mouse button specification (e.g. `MousePrimary` or `MouseDPrimary` for double click).