libnkutils Format string format: libnkutils Reference Manual

libnkutils Format string format

Format string format — specification of an NkFormatString

Format strings

A format string can contain references to a data in 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:[separatorrange-startseparatorrange-end[separatorsubstitute-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]}`.

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.`