Expand description
§Configuration Conversion Command
The convert command transforms TOML configuration files into JSON format
suitable for consumption by QuickShell. This is the bridge between the
human-friendly TOML authoring format and the QML-friendly JSON runtime format.
§Usage
# Convert with auto-named output (config.toml → config.json)
fernctl convert config.toml
# Convert with explicit output path
fernctl convert config.toml --output theme.json
# With verbose output
fernctl convert config.toml -v§Why Two Formats?
TOML and JSON serve different purposes in the Fern ecosystem:
| Aspect | TOML (Input) | JSON (Output) |
|---|---|---|
| Audience | Human authors | QML runtime |
| Comments | ✓ Supported | ✗ Not in spec |
| Readability | Optimized | Adequate |
| Parsing | Rust (fernctl) | JavaScript (QML) |
| Editing | By users | Never |
§Conversion Pipeline
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ config.toml │────▶│ Validate │────▶│ config.json │
│ (user file) │ │ & Transform │ │ (QML runtime) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
Human-readable Type-safe Rust Structured for
with comments domain model QML consumption§Validation During Conversion
Conversion is not a simple format translation. The configuration passes through full validation before JSON output is generated. This ensures that invalid configurations are caught early, before they reach QuickShell.
config.toml (valid TOML, invalid values)
│
▼
┌────────────────────────────────────────┐
│ Parse TOML │ ✓ Succeeds
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ Validate Values │ ✗ Fails: "#gg0000" invalid
│ - Check color formats │
│ - Verify ranges │
│ - Resolve defaults │
└────────────────────────────────────────┘
│
▼
Error returned, no JSON generated§Output Format
The generated JSON follows a specific structure optimized for QML:
{
"variant": "dark",
"colors": {
"background": "#1e1e2e",
"foreground": "#cdd6f4",
"accent": "#89b4fa",
...
},
"bar": {
"height": 32,
"position": "top",
...
},
...
}§Atomicity
Conversion is atomic — if any step fails, no output file is created or modified. This prevents partial writes that could leave QuickShell with a corrupted configuration.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Success │ │ Failure │ │ Failure │
│ Path │ │ (Parse) │ │ (Validate) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
JSON written No file touched No file touched§Exit Codes
| Code | Meaning |
|---|---|
0 | Conversion succeeded |
1 | Conversion failed (parse error, validation error, I/O error) |
§Programmatic Usage
ⓘ
use fernctl::commands::convert::{run, ConvertOptions};
use fernctl::adapters::{TomlConfigAdapter, FileSystemAdapter};
let config_adapter = TomlConfigAdapter::new();
let persist_adapter = FileSystemAdapter::new();
let options = ConvertOptions { verbose: true };
run(
Path::new("config.toml"),
Path::new("config.json"),
options,
&config_adapter,
&persist_adapter,
)?;Structs§
- Convert
Options - Options for the convert command.
- Convert
Result - Result of a successful conversion.
Functions§
- derive_
output_ path - Derives the output path from an input path.
- run
- Converts a TOML configuration file to JSON.