Large KiCad files often need narrow source scans before full tree or OOP parsing would be justified.
Describe generic S-expression form selection by head, exact path, depth, and pruned subtrees.
Tests must prove head, path, depth, and prune filters select the intended forms without materializing unrelated forms.
A selector is public when PCB, schematic, and library scanners can reuse it without file-type-specific regex logic.
Projection callers need stable source ranges that can be inspected, reparsed, or mapped to diagnostics without keeping a full parse tree.
Represent one complete selected S-expression form with head, path, depth, offsets, source location, and helpers for text and parse access.
Tests must prove selected span text is exact, offsets are stable, and reparsing the span produces the selected form.
A span is public when downstream scan tools can safely defer full parsing until a selected form is actually needed.
Large KiCad files often need selected typed objects without constructing the full file model or a file-type-specific projection facade.
iter_kicad_objects_from_file and
iter_kicad_objects_from_text select source forms with the
generic projection scanner and hydrate only the requested object type
through that class's from_sexp factory.
The default selectors cover whole-file roots, PCB footprints and routing
objects, library symbols, placed schematic symbols, common schematic
primitives, models, and embedded files. This is the documented narrow
read path for schematic object scans. A named
KiCadSchematicProjection facade should remain deferred until
a concrete source-span-preserving schematic workload needs one.
User-facing workflow selection is canonical in
Project Workflows And
Read-Path Selection.
Tests must prove the file reader uses the default selector, hydrates selected typed objects, distinguishes library symbols from placed schematic symbols, and filters embedded-file forms without materializing unrelated objects.
A targeted KiCad object reader is public when callers can scan a known object family from source text or a file using promoted package-root exports and receive normal typed domain objects.
OOP model callers need one predictable query view for schematics, boards, footprints, projects, and designs instead of ad hoc list traversal.
Provide a read-only live sequence with type/name filtering, exact-attribute filtering, count, first, and materialization helpers.
Tests must prove the collection is sequence-like, live, filterable by class and class name, and rejects direct mutation.
A model-owned collection facade is public when it supports common query helpers without owning or mutating the underlying model list.