Skip to main content

Crate general_spice_core

Crate general_spice_core 

Source
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 — the Dialect enum and the device-letter overlay table. Some device letters mean different things in each dialect (P is 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-core ast::Statement enum, shared by both dialects. Dialect-specific meaning lives in the overlay tables, not as extra AST variants.
  • parser — turns preprocessed lines into ast::Statements. Two entry points: parser::parse for a statement fragment (what every unit test in this crate uses), and parser::parse_document for 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::diagnostics flags 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), .subckt call resolution with circular- reference detection (symbols::subckt_resolution), .model reference resolution (symbols::model_resolution), and dialect- specific .param scope chains (symbols::ngspice_param_scope, symbols::xyce_param_scope).
  • include — multi-file .include/.lib resolution (include::graph), behind a include::resolve::FileSystem trait 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 Statement enum 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 in crate::parser::ngspice/crate::parser::xyce; dialect-specific meaning (e.g. what a given device letter is) lives in crate::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 .PARAM grammar and a separate runtime/behavioral-source grammar; Xyce has one grammar plus special forms for TABLE/polynomial sources), all producing the same shared Expr tree defined in ast. token holds the shared tokenizer every parser here is built on; diagnostics holds cross-dialect “gotcha” lints; wiring_* connects parsed expressions back to the statements that contain them.
include
Multi-file .include/.lib resolution: turns an entry netlist file plus whatever it pulls in via .include/.lib into one merged statement list, with diagnostics for unresolvable paths, circular includes, and missing .lib sections. Start with graph::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 before crate::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) into Statements. Two entry points: parse for an arbitrary statement fragment, parse_document for a complete real netlist file (handles the mandatory title line). Dialect-specific parsing logic lives in ngspice and xyce; this module dispatches to whichever one matches the requested Dialect plus holds the shared ParseError/ ParseResult types.
symbols
Scope-tree construction and every symbol-resolution diagnostic pass built on it. Start with scope::build_scope_tree to turn a parsed statement list into a scope::Scope tree, 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).