Expand description
§Formatting system
Many blocks have a format configuration option, which allows to heavily customize the block’s
appearance. In short, each block with format option provides a set of values, which are
displayed according to format. format’s value is just a text with embedded variables.
Similarly to PHP and shell, variable name must start with a $:
this is a variable: -> $var <-.
Also, format strings can embed icons. For example, ^icon_ping in " ^icon_ping $ping " gets
substituted with a “ping” icon from your icon set. For a complete list of icons, see
this.
§Types
The allowed types of variables are:
| Type | Default formatter |
|---|---|
| Text | str |
| Number | eng |
| Datetime | datetime |
| Duration | duration |
| Flag | N/A |
§Formatters
A formatter is something that converts a value into a text. Because there are many ways to do
this, a number of formatters is available. Formatter can be specified using the syntax similar
to method calls in many programming languages: <variable>.<formatter>(<args>). For example:
$title.str(min_w:10, max_w:20).
§str - Format text
| Argument | Description | Default value |
|---|---|---|
min_width or min_w | if text is shorter it will be padded using spaces | 0 |
max_width or max_w | if text is longer it will be truncated | Infinity |
width or w | Text will be exactly this length by padding or truncating as needed | N/A |
rot_interval | if text is longer than max_width it will be rotated every rot_interval seconds, if set | None |
rot_separator | if text is longer than max_width it will be rotated with this seporator | "|" |
Note: width just changes the values of both min_width and max_width to be the same. Use width if you want the values to be the same, or the other two otherwise. Don’t mix width with min_width or max_width.
§eng - Format numbers using engineering notation
| Argument | Description | Default value |
|---|---|---|
width or w | the resulting text will be at least width characters long | 2 |
unit or u | some values have a unit, and it is possible to convert them by setting this option | N/A |
hide_unit | hide the unit symbol | false |
unit_space | have a whitespace before unit symbol | false |
prefix or p | specify this argument if you want to set the minimal SI prefix | N/A |
hide_prefix | hide the prefix symbol | false |
prefix_space | have a whitespace before prefix symbol | false |
force_prefix | force the prefix value instead of setting a “minimal prefix” | false |
pad_with | the character that is used to pad the number to be width long | (a space) |
range | a range of allowed values, in the format <start>..<end>, inclusive. Both start and end are optional. Can be used to, for example, hide the block when the value is not in a given range. | .. |
§bar - Display numbers as progress bars
| Argument | Description | Default value |
|---|---|---|
width or w | the width of the bar (in characters) | 5 (1 for vertical) |
max_value | which value is treated as “full”. For example, for battery level 100 is full. | 100 |
vertical or v | whether to render the bar vertically or not | false |
§tally - Display numbers as tally marks
| Argument | Description | Default value |
|---|---|---|
style or s | One of chinese_counting_rods/ccr, chinese_tally/ct, western_tally/wt, western_tally_ungrouped/wtu | western_tally |
§pango-str - Just display the text without pango markup escaping
No arguments.
§datetime - Display datetime
| Argument | Description | Default value |
|---|---|---|
format or f | chrono docs for all options. | '%a %d/%m %R' |
locale or l | Locale to apply when formatting the time | System locale |
§duration/dur - Format durations
| Argument | Description | Default value |
|---|---|---|
hms | Should the format be hours:minutes:seconds.milliseconds | false |
max_unit | The largest unit to display the duration with (see below for the list of all possible units) | hms ? h : y |
min_unit | The smallest unit to display the duration with (see below for the list of all possible units) | s |
units | The number of units to display | min(# of units between max_unit and `min_unit``, 2) |
round_up | Round up to the nearest minimum displayed unit | true |
unit_space | Should there be a space between the value and unit symbol (not allowed when hms:true) | false |
pad_with | The character that is used to pad the numbers | hms ? 0 : (a space) |
leading_zeroes | If fewer than units are non-zero should leading numbers that have a value of zero be shown | true |
| Unit | Description |
|---|---|
| y | years |
| w | weeks |
| d | days |
| h | hours |
| m | minutes |
| s | seconds |
| ms | milliseconds |
§Handling missing placeholders and incorrect types
Some blocks allow missing placeholders, for example bluetooth’s
“percentage” may be absent if the device is not supported. To handle such cases it is possible
to queue multiple formats together by using | symbol: <something that can fail>|<otherwise try this>|<or this>.
In addition, formats can be recursive. To set a format inside of another format, place it
inside of {}. For example, in Percentage: {$percentage|N/A} the text “Percentage: “ will be
always displayed, followed by the actual percentage or “N/A” in case percentage is not
available. This example does exactly the same thing as Percentage: $percentage|Percentage: N/A
§How to use flags
Some blocks provide flags, which can be used to change the format based on some criteria. For
example, taskwarrior defines done if the count is zero. In
general, flags are used in this way:
$a{a is set}|$b$c{b and c are set}|${b|c}{b or c is set}|neither flag is set