The Format String System is a template engine that controls how module output is rendered in fastfetch. It provides a sophisticated syntax for variable substitution, conditional rendering, color formatting, and text manipulation. Each module defines its available placeholders, and users customize output by writing format strings that reference these placeholders.
For general display options (colors, separators, key widths), see Output Formatting and Display Options. For the module execution framework that invokes format strings, see Module System Architecture.
Sources: src/common/format.c1-414
The format string system consists of three main components: argument registration by modules, parsing and evaluation by the format engine, and rendering utilities for special data types.
Sources: src/common/format.c123-413 src/common/format.c9-59 src/common/format.c69-96
Modules register format arguments using the FFformatarg structure. Each argument has a name (optional), a type, and a pointer to the data value. The format engine knows how to convert each type to a string representation.
| Type | Enum Value | C Type | Description |
|---|---|---|---|
| Null | FF_FORMAT_ARG_TYPE_NULL | N/A | No value, skipped during rendering |
| Integer | FF_FORMAT_ARG_TYPE_INT | int32_t* | Signed 32-bit integer |
| Unsigned Integer | FF_FORMAT_ARG_TYPE_UINT | uint32_t* | Unsigned 32-bit integer |
| 64-bit Unsigned | FF_FORMAT_ARG_TYPE_UINT64 | uint64_t* | Unsigned 64-bit integer |
| 16-bit Unsigned | FF_FORMAT_ARG_TYPE_UINT16 | uint16_t* | Unsigned 16-bit integer |
| 8-bit Unsigned | FF_FORMAT_ARG_TYPE_UINT8 | uint8_t* | Unsigned 8-bit integer |
| C String | FF_FORMAT_ARG_TYPE_STRING | const char* | Null-terminated string |
| String Buffer | FF_FORMAT_ARG_TYPE_STRBUF | FFstrbuf* | Dynamic string buffer |
| Float | FF_FORMAT_ARG_TYPE_FLOAT | float* | Single-precision floating point |
| Double | FF_FORMAT_ARG_TYPE_DOUBLE | double* | Double-precision floating point |
| Boolean | FF_FORMAT_ARG_TYPE_BOOL | bool* | Boolean (rendered as "true"/"false") |
| List | FF_FORMAT_ARG_TYPE_LIST | FFlist* | List of FFstrbuf (comma-separated) |
Sources: src/common/format.c9-59
Format strings use curly braces {} to denote placeholders. The format engine supports three placeholder addressing modes:
| Syntax | Description | Example |
|---|---|---|
{} | Auto-increment counter (1, 2, 3, ...) | {} @ {} → "CPU @ 3.5 GHz" |
{1} | Positional index (1-based) | {2} ({1}) → "3.5 GHz (CPU)" |
{name} | Named placeholder | {cpu-name} @ {freq} → "CPU @ 3.5 GHz" |
The argument index resolution logic is implemented in getArgumentIndex():
Sources: src/common/format.c69-96 src/common/format.c307-318
| Sequence | Result | Purpose |
|---|---|---|
{{ | { | Literal opening brace |
{-} | (stop parsing) | Truncate output at this point |
Sources: src/common/format.c144-149 src/common/format.c164-165
The format system supports conditional blocks that render content only when a specified argument is set (non-zero, non-empty, non-null).
{?name}...{?}Renders the enclosed content only if the argument name is "set" (has a meaningful value).
Syntax: {?placeholder}content{?}
Example: {name}{?temp} @ {temp}{?} → "CPU @ 45°C" (if temp is set) or "CPU" (if temp is not set)
{/name}...{/}Renders the enclosed content only if the argument name is NOT set.
Syntax: {/placeholder}content{/}
Example: {name}{/temp} (no temp data){/} → "CPU (no temp data)" (if temp is not set) or "CPU" (if temp is set)
The formatArgSet() function determines whether an argument is "set":
| Argument Type | Condition for "Set" |
|---|---|
DOUBLE | value > 0.0 |
FLOAT | value > 0.0 |
INT | value > 0 |
STRBUF | length > 0 |
STRING | Non-NULL and not empty |
UINT8/UINT16/UINT | value > 0 |
BOOL | value == true |
LIST | length > 0 |
Sources: src/common/format.c199-223 src/common/format.c225-249 src/common/format.c107-121
Color codes allow inline color changes within format strings. The system integrates with fastfetch's color configuration.
| Syntax | Description | Example |
|---|---|---|
{#rrggbb} | RGB hex color | {#ff0000}red text{#} |
{#color-name} | Named color | {#red}red text{#} |
{#} | Reset to default | Closes color block |
When not in pipe mode (!instance.config.display.pipe), the parser generates ANSI escape sequences:
{#rrggbb} → \e[<parsed-color>m{#} → \e[0m (FASTFETCH_TEXT_MODIFIER_RESET)The color parsing is delegated to ffOptionParseColorNoClear(), which translates color specifications into ANSI SGR codes.
Sources: src/common/format.c252-261 src/common/format.c189-196
The format system provides several operators for text manipulation: truncation, padding, and substring extraction.
{placeholder:length}Truncates the value to length characters, trimming trailing whitespace.
Example: {name:10} with "Very Long CPU Name" → "Very Long"
| Syntax | Alignment | Padding |
|---|---|---|
{placeholder<length} | Left-aligned | Pad right with spaces |
{placeholder>length} | Right-aligned | Pad left with spaces |
Example: {name<15} with "CPU" → "CPU "
{placeholder:-length}Truncates to length - 1 characters and appends an ellipsis character (…).
Example: {name:-10} with "Very Long CPU Name" → "Very Long…"
{placeholder~start,end}Extracts characters from index start to end (0-based). Negative indices count from the end.
Syntax:
{placeholder~start} → Extract from start to end{placeholder~start,end} → Extract from start to endExamples:
{name~5} with "Hello World" → "World"{name~0,5} with "Hello World" → "Hello"{name~-5} with "Hello World" → "World"Sources: src/common/format.c320-408
The format system supports referencing constants and environment variables through the {$} syntax.
{$1}, {$-1}Constants are user-defined values stored in instance.config.display.constants (an FFlist of FFstrbuf). They are indexed 1-based (or negative for counting from the end).
Configuration: Constants are defined in the display.constants array in the configuration file.
Example:
"constants": ["My Custom Value", "Another Value"]{$1} → "My Custom Value"{$-1} → "Another Value"{$VAR_NAME}If the placeholder cannot be parsed as a number, it's treated as an environment variable name.
Example: {$HOME} → "/home/username"
Sources: src/common/format.c263-291 src/options/display.c472-480
Each module defines its available placeholders in the JSON schema. The schema documents the placeholder names, indices, and descriptions for every module.
From the JSON schema, the CPU module supports the following placeholders:
| Index | Placeholder | Description |
|---|---|---|
| 1 | {name} | CPU name |
| 2 | {vendor} | CPU vendor |
| 3 | {cores-physical} | Physical core count |
| 4 | {cores-logical} | Logical core count |
| 5 | {cores-online} | Online core count |
| 6 | {freq-base} | Base frequency (formatted) |
| 7 | {freq-max} | Max frequency (formatted) |
| 8 | {temperature} | Temperature (formatted) |
| 9 | {core-types} | Logical core count grouped by frequency |
| 10 | {packages} | Processor package count |
| 11 | {march} | X86-64 CPU microarchitecture |
Modules follow this pattern to register format arguments:
FFformatarg array with named placeholdersffPrintFormat() or custom printing functionSources: doc/json_schema.json320-323 doc/json_schema.json276-517
The core parsing loop in ffParseFormatString() implements a state machine that processes the format string character by character, handling nested conditionals and various placeholder types.
| Variable | Type | Purpose |
|---|---|---|
argCounter | uint32_t | Auto-increment counter for {} placeholders |
numOpenIfs | uint32_t | Nesting depth of {?} conditionals |
numOpenNotIfs | uint32_t | Nesting depth of {/} conditionals |
placeholderValue | FFstrbuf | Temporary buffer for placeholder content |
Sources: src/common/format.c123-413
The format system reads display configuration from instance.config.display (type FFOptionsDisplay) to control rendering behavior.
| Option | Type | Usage in Format System |
|---|---|---|
pipe | bool | Disables all ANSI color codes when true |
constants | FFlist | Source for {$N} constant placeholders |
colorOutput | FFstrbuf | Default output color after color resets |
fractionNdigits | int8_t | Decimal places for float/double formatting |
fractionTrailingZeros | enum | Whether to keep trailing zeros in floats |
Sources: src/common/format.c35-38 src/common/format.c192-193 src/common/format.c280-287 src/common/format.c411-412 src/options/display.h35-94
While the core format system handles general text substitution, specialized formatting utilities handle percentages and temperatures with color-coding and visual indicators.
Percentage values can be rendered as:
45.3% with optional color-coding[■■■■■-----] with multi-color sections45.3% [■■■■■-----]These are rendered by ffPercentAppendBar() and ffPercentAppendNum() in src/common/percent.c
Temperature values are rendered with color-coding based on thresholds by ffTempsAppendNum() in src/common/temps.c The format system treats formatted percentages and temperatures as opaque strings once rendered.
Integration Pattern:
ffPercentAppendBar())FFstrbufFF_FORMAT_ARG_TYPE_STRBUF{placeholder}Sources: src/common/percent.c56-167 src/common/temps.c6-65
Format: {name}{?version} {version}{?} Result: "Bash 5.1" (if version available) or "Bash" (if not) Format: {name}{?temp} @ {temp}{?}{?freq} @ {freq}{?} Result: "CPU @ 45°C @ 3.5 GHz" (both available) "CPU @ 45°C" (only temp available) "CPU @ 3.5 GHz" (only freq available) "CPU" (neither available) Format: {#ff0000}{name}{#} {#00ff00}{value}{#} Result: Red name, green value Format: {name<20} {value>10} Result: "CPU 3.5 GHz" Format: {name} on {$HOSTNAME} Result: "CPU on mycomputer" Sources: doc/json_schema.json276-517
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.