Module convert

Source
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:

AspectTOML (Input)JSON (Output)
AudienceHuman authorsQML runtime
Comments✓ Supported✗ Not in spec
ReadabilityOptimizedAdequate
ParsingRust (fernctl)JavaScript (QML)
EditingBy usersNever

§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

CodeMeaning
0Conversion succeeded
1Conversion 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§

ConvertOptions
Options for the convert command.
ConvertResult
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.