Crate kiutils_kicad

Expand description

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

Round-trip + unknown preservation tests: https://github.com/Milind220/kiutils-rs/blob/main/crates/kiutils_kicad/tests/integration.rs
CLI contract tests (kiutils-inspect): https://github.com/Milind220/kiutils-rs/blob/main/crates/kiutils_kicad/tests/inspect_cli.rs

§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

Lossless round-trip: Writing a parsed file with WriteMode::Lossless produces byte-identical output to the original input, including whitespace and comments.
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.
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.
Legacy compatibility: Files using legacy root tokens (see table above) parse in compatibility mode with a legacy_root diagnostic to inform callers.
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.