kiutils_rs/
lib.rs

1#![warn(missing_docs)]
2//! # kiutils-rs
3//!
4//! **Pure-Rust, lossless KiCad S-expression document API for agent workflows.**
5//! Designed for parse -> typed edit -> write with minimal diff noise and explicit forward-compat
6//! surfaces.
7//!
8//! ## Why this crate (for AI agents and automation)
9//! | Capability | `kiutils-rs` | Python `kiutils` | `KicadModTree` | KiCad IPC Rust API (`kicad-api-rs-official`) |
10//! |---|---|---|---|---|
11//! | File round-trip target | First-class (`WriteMode::Lossless`) | SCM-friendly goal, with known round-trip caveats in docs | Generator-centric (creates footprints; not general file parser API) | Runtime IPC API (different problem) |
12//! | Unknown/future syntax | Exposed as typed unknown carriers (`UnknownNode`, `UnknownField`) | Known issues document format/ordering caveats in some cases | Focused on scripted footprint construction | N/A for S-expression file editing |
13//! | Architecture for tooling | 3 layers (`kiutils-sexpr` -> `kiutils-kicad` -> `kiutils-rs`) | Single Python package/dataclass stack | Tree-based node generator framework | IPC client binding |
14//! | Public tests/docs signal | Integration tests assert byte-equal lossless writes across formats | Project tests exist; changelog tracks format fixes over time | README/docs emphasize footprint generation workflows | README states docs are not yet available |
15//!
16//! Source evidence:
17//! - This workspace architecture: <https://github.com/Milind220/kiutils-rs/blob/main/README.md>
18//! - Lossless/unknown round-trip tests:
19//!   <https://github.com/Milind220/kiutils-rs/blob/main/crates/kiutils_kicad/tests/integration.rs>
20//! - Python `kiutils` known issues:
21//!   <https://github.com/mvnmgrx/kiutils/blob/master/docs/misc/known-issues.rst>
22//! - Python `kiutils` changelog:
23//!   <https://github.com/mvnmgrx/kiutils/blob/master/CHANGELOG.md>
24//! - `KicadModTree` repository README:
25//!   <https://github.com/pointhi/kicad-footprint-generator/blob/master/README.md>
26//! - Official KiCad Rust IPC README:
27//!   <https://github.com/Milind220/kicad-api-rs-official/blob/main/README.md>
28//!
29//! ## V1 API scope
30//! - `.kicad_pcb`
31//! - `.kicad_mod`
32//! - `fp-lib-table`
33//! - `sym-lib-table`
34//! - `.kicad_dru`
35//! - `.kicad_pro`
36//!
37//! Compatibility target:
38//! - Primary: KiCad v10
39//! - Secondary: KiCad v9
40//!
41//! ## Quickstart
42//! ```rust,no_run
43//! use kiutils_rs::{PcbFile, WriteMode};
44//!
45//! fn main() -> Result<(), Box<dyn std::error::Error>> {
46//!     let mut doc = PcbFile::read("input.kicad_pcb")?;
47//!     doc.set_generator("kiutils-rs-agent")
48//!         .set_generator_version("0.1.0")
49//!         .upsert_property("Owner", "EDA-Agent");
50//!     doc.write_mode("output.kicad_pcb", WriteMode::Lossless)?;
51//!     Ok(())
52//! }
53//! ```
54//!
55//! Crate package name: `kiutils-rs`
56//! Rust import path: `kiutils_rs`
57
58/// Diagnostics, errors, and write behavior controls.
59pub use kiutils_kicad::{
60    Diagnostic, Error, KiCadSeries, Severity, Span, UnknownField, UnknownNode, VersionPolicy,
61    WriteMode,
62};
63
64/// Design-rules (`.kicad_dru`) APIs.
65pub use kiutils_kicad::{DesignRuleSummary, DesignRulesAst, DesignRulesDocument, DesignRulesFile};
66
67/// Footprint (`.kicad_mod`) APIs.
68pub use kiutils_kicad::{FootprintAst, FootprintDocument, FootprintFile};
69
70/// Library table (`fp-lib-table`, `sym-lib-table`) APIs.
71pub use kiutils_kicad::{
72    FpLibTableAst, FpLibTableDocument, FpLibTableFile, SymLibTableAst, SymLibTableDocument,
73    SymLibTableFile,
74};
75
76/// PCB (`.kicad_pcb`) APIs.
77pub use kiutils_kicad::{
78    PcbArcSummary, PcbAst, PcbDimensionSummary, PcbDocument, PcbFile, PcbFootprintSummary,
79    PcbGeneratedSummary, PcbGraphicSummary, PcbGroupSummary, PcbLayer, PcbNet, PcbProperty,
80    PcbSegmentSummary, PcbSetupSummary, PcbTargetSummary, PcbViaSummary, PcbZoneSummary,
81};
82
83/// Project (`.kicad_pro`) APIs.
84pub use kiutils_kicad::{ProjectAst, ProjectDocument, ProjectExtra, ProjectFile};
kiutils_rs/lib.rs

kiutils_rs/
lib.rs
