kiutils_kicad 0.3.0

Typed KiCad document model and codecs for seamless, lossless edit round-trips
Documentation

kiutils-kicad

Typed KiCad file document layer built on top of kiutils-sexpr.

If you want stable end-user imports, use kiutils-rs. This crate exposes the implementation-layer API and additional file families.

Scope

  • .kicad_pcb
  • .kicad_mod
  • .kicad_sch
  • .kicad_sym
  • fp-lib-table
  • sym-lib-table
  • .kicad_dru
  • .kicad_pro
  • .kicad_wks

Core behavior

  • Default write mode is lossless (WriteMode::Lossless)
  • Unknown tokens are captured on typed ASTs (unknown_nodes, unknown_fields)
  • write_mode(..., WriteMode::Canonical) available for normalized output
  • Version diagnostics produced post-parse for forward-compat signaling

Evidence:

Quickstart

use kiutils_kicad::{SchematicFile, WriteMode};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = SchematicFile::read("input.kicad_sch")?;
    doc.write_mode("output.kicad_sch", WriteMode::Lossless)?;
    Ok(())
}

Policy notes:

  • AST *_count fields are convenience counters, not strict stability promises.
  • Unknown-token diagnostics are developer-facing; summarize before showing end users.
  • .kicad_dru rule conditions are preserved as strings in v1.

Token alias policy

KiCad file formats have evolved over major versions, sometimes renaming root tokens or restructuring S-expression nodes. This crate follows a consistent policy for handling these differences:

Format Modern token Legacy alias Behavior
PCB kicad_pcb (none) Only modern accepted
Footprint footprint module Both accepted; legacy_root diagnostic emitted
Schematic kicad_sch (none) Only modern accepted
Symbol lib kicad_symbol_lib (none) Only modern accepted
Worksheet kicad_wks page_layout Both accepted; legacy_root diagnostic emitted
Design rules kicad_dru (rootless) Rootless format accepted
Lib tables fp_lib_table / sym_lib_table (none) Only modern accepted

Parser guarantees

  1. Lossless round-trip: Writing a parsed file with WriteMode::Lossless produces byte-identical output to the original input, including whitespace and comments.
  2. Unknown token preservation: Any S-expression node not recognized by the typed AST parser is captured in unknown_nodes / unknown_fields vectors and preserved through round-trip writes.
  3. Forward compatibility: Files from newer KiCad versions parse without error; unrecognized tokens land in unknown vectors and a future_format diagnostic is emitted when the version number exceeds the known range.
  4. Legacy compatibility: Files using legacy root tokens (see table above) parse in compatibility mode with a legacy_root diagnostic to inform callers.
  5. Typed AST is read-only over CST: The typed AST is derived from the CST on parse. Mutations go through document setter APIs that modify the CST directly, then re-derive the AST, ensuring CST remains the source of truth.