Expand description
general_spice_core — a dialect-agnostic parser and symbol-resolution engine
for SPICE-family circuit netlists (ngspice and Xyce today; a third proprietary dialect
planned once reference documentation is available).
This crate does not simulate circuits. It turns netlist text into
structured data an editor or tool can use for diagnostics, hover,
go-to-definition, and completion — the kind of thing a language server
needs, without being tied to the Language Server Protocol itself. It is
consumed two ways in practice: embedded directly as a library (e.g. from
a Tauri app’s Rust backend, calling straight into these functions with
no IPC layer involved), or wrapped by a separate tower-lsp-based
binary that speaks LSP over stdio for editors.
§Is this crate right for your use case?
Yes, if you want to: parse ngspice or Xyce netlist text into a
structured AST; detect duplicate .subckt/.model names, undefined
subcircuit/model references, or circular .subckt/.include chains;
resolve .param scoping (including the dialect-specific differences —
see docs/GRAMMAR.md in the repository); parse SPICE expressions
(arithmetic, behavioral B/E/G-source forms) into a typed tree; or
resolve multi-file .include/.lib netlists into one merged document.
No, if you want to: actually simulate a circuit (this crate has no
solver — pair it with a real ngspice/Xyce process for that), fully
validate every SPICE statement type (some statements are captured
structurally as raw text rather than semantically modeled — see
docs/GRAMMAR.md’s phase plan for what’s covered), or work with
that third proprietary dialect’s netlists (not yet supported).
§Architecture
One common core plus per-dialect overlays — never two independent grammars, and never one grammar with dialect checks scattered through shared logic. Concretely:
dialect— theDialectenum and the device-letter overlay table. Some device letters mean different things in each dialect (Pis a coupled-multiconductor line in ngspice but an S-parameter port device in Xyce); resolving that ambiguity is this module’s job, done once, rather than re-derived by every caller.lexer— dialect-aware comment stripping and line-continuation joining, run before any statement-level parsing.ast— the common-coreast::Statementenum, shared by both dialects. Dialect-specific meaning lives in the overlay tables, not as extra AST variants.parser— turns preprocessed lines intoast::Statements. Two entry points:parser::parsefor a statement fragment (what every unit test in this crate uses), andparser::parse_documentfor a whole real file (which has a mandatory title line — see that function’s docs for why the distinction matters).expr— SPICE expression parsing. Not one grammar: ngspice alone has a compile-time grammar (.param/.func/brace-expressions) and a separate runtime grammar (B/E/G-source expressions) with a genuinely different function set and operator semantics. Xyce has one unified grammar instead, but with context-dependent restrictions on what an expression may reference.expr::diagnosticsflags the cross-dialect false cognates (^means power in ngspice, boolean XOR in Xyce;log()is natural log in ngspice, base-10 in Xyce).symbols— scope-tree construction (symbols::scope) and the diagnostic passes built on it: name uniqueness (symbols::uniqueness),.subcktcall resolution with circular- reference detection (symbols::subckt_resolution),.modelreference resolution (symbols::model_resolution), and dialect- specific.paramscope chains (symbols::ngspice_param_scope,symbols::xyce_param_scope).include— multi-file.include/.libresolution (include::graph), behind ainclude::resolve::FileSystemtrait so it’s testable without touching real disk.
For the full grammar reference this crate implements against —
including exactly what’s common between ngspice and Xyce, what
diverges, and why — see docs/GRAMMAR.md in the repository root. For
what’s implemented vs. planned, see progress.core.yaml.
§Quick start: parsing a single file
use general_spice_core::{ast::Statement, lexer, parser, Dialect};
let source = "\
Example RC circuit
R1 1 0 1k
C1 1 0 10n
.end
";
let lines = lexer::preprocess(source, Dialect::Ngspice);
// parse_document (not parse) because this is a whole real file: the
// first line is always the title, per the SPICE convention both
// dialects share.
let results = parser::parse_document(&lines, Dialect::Ngspice);
let mut device_names = Vec::new();
for result in &results {
if let Ok(Statement::ElementInstance(ei)) = result {
device_names.push(ei.name.as_str());
}
}
assert_eq!(device_names, vec!["R1", "C1"]);§Quick start: diagnostics (undefined subcircuit reference)
use general_spice_core::{ast::Statement, lexer, parser, symbols, Dialect};
let source = "\
Circuit with a typo'd subckt reference
X1 in out amplifier
.end
";
let lines = lexer::preprocess(source, Dialect::Ngspice);
let parsed = parser::parse_document(&lines, Dialect::Ngspice);
let statements: Vec<Statement> = parsed.into_iter().flatten().collect();
let tree = symbols::scope::build_scope_tree(&statements)
.expect("well-formed .subckt/.ends nesting");
let diagnostics = symbols::subckt_resolution::resolve_subckt_calls(&tree, Dialect::Ngspice);
assert_eq!(diagnostics.len(), 1);
assert!(diagnostics[0].message.contains("undefined subcircuit"));§Quick start: multi-file .include resolution
use general_spice_core::include::graph::resolve_includes;
use general_spice_core::include::resolve::FakeFileSystem;
use general_spice_core::include::source_map::SourceMap;
use general_spice_core::Dialect;
use std::path::Path;
let mut fs = FakeFileSystem::new();
fs.insert(
"/top.cir",
"top-level circuit\nR1 1 2 100\n.include /parts.cir\n.end\n",
);
fs.insert("/parts.cir", "C1 2 0 10n\n");
let mut source_map = SourceMap::new();
let (statements, diagnostics) =
resolve_includes(Path::new("/top.cir"), &fs, Dialect::Ngspice, &mut source_map);
assert!(diagnostics.is_empty());
// title (Comment) + R1 (top.cir) + C1 (spliced in from parts.cir) +
// .end (not yet semantically modeled, captured as Unrecognized) —
// all merged in document order.
assert_eq!(statements.len(), 4);FakeFileSystem is the same in-memory test double this crate’s own
test suite uses; swap in a real include::resolve::FileSystem
implementation backed by std::fs to resolve real files.
Re-exports§
pub use dialect::Dialect;
Modules§
- ast
- The dialect-agnostic AST: the
Statementenum and the payload structs for its more complex variants. This is the common core in the “common core + per-dialect overlays” architecture (see the crate-level docs) — nothing in this module knows which dialect (ngspice or Xyce) a statement came from. Dialect-specific parsing lives incrate::parser::ngspice/crate::parser::xyce; dialect-specific meaning (e.g. what a given device letter is) lives incrate::dialect. - dialect
- Which SPICE dialect a document is being parsed as, and the per-dialect device-letter overlay table.
- expr
- Expression parsing: multiple dialect- and context-specific grammars
(ngspice has a distinct compile-time
.PARAMgrammar and a separate runtime/behavioral-source grammar; Xyce has one grammar plus special forms forTABLE/polynomial sources), all producing the same sharedExprtree defined inast.tokenholds the shared tokenizer every parser here is built on;diagnosticsholds cross-dialect “gotcha” lints;wiring_*connects parsed expressions back to the statements that contain them. - include
- Multi-file
.include/.libresolution: turns an entry netlist file plus whatever it pulls in via.include/.libinto one merged statement list, with diagnostics for unresolvable paths, circular includes, and missing.libsections. Start withgraph::resolve_includes. - lexer
- Line-level preprocessing: strips comments, joins continuation lines
(
+-prefixed, and ngspice’s\-suffixed physical-line continuation), and tracks which real source lines each resulting logical line came from. This always runs beforecrate::parser::parse/crate::parser::parse_document— the parser never sees raw, un-preprocessed source. Entry point:preprocess. - parser
- Turns preprocessed lines (
crate::lexer::preprocess’s output) intoStatements. Two entry points:parsefor an arbitrary statement fragment,parse_documentfor a complete real netlist file (handles the mandatory title line). Dialect-specific parsing logic lives inngspiceandxyce; this module dispatches to whichever one matches the requestedDialectplus holds the sharedParseError/ParseResulttypes. - symbols
- Scope-tree construction and every symbol-resolution diagnostic pass
built on it. Start with
scope::build_scope_treeto turn a parsed statement list into ascope::Scopetree, then feed that tree into whichever diagnostic passes you need — they’re independent of each other and can be run in any order (or skipped).