Expand description
Native source-mapped PlusCal grammar parsing and translation.
parse produces a source AST, not a translated TLA+ specification.
translate follows the pinned translator’s normalization, scoped renaming,
expression substitution, process/fairness and procedure semantics. Calls use
runtime stack frames, including recursion. Resource limits and generated-name
collisions remain explicit refusals. Expression slices retain counted nesting;
generation checks TLA+ syntax, and the whole-module API separately checks names
and levels. The original source AST is preserved.
No Java runtime is used by this crate.
let source = "--algorithm A begin L: skip; end algorithm";
let parsed = dive_pluscal::parse(source, &dive_pluscal::Options::default())?;
assert_eq!(parsed.algorithm.name.text, "A");
assert_eq!(parsed.text(parsed.algorithm.span), Some(source));Modules§
- ast
- Source grammar nodes. Spelling and byte ranges are never normalized away.
- rewrite
- Bounded source editing and translation-body checksum interoperability. Bounded translation-block editing and pinned line-concatenation CRC32.
Structs§
- Algorithm
Checksum - Exact reference AST bytes and the corresponding algorithm checksum. This is serialization evidence, not TLA admission or a model proof.
- Diagnostic
- Deterministic diagnostic over original source bytes.
- Inserted
Label - A generated label associated with its original statement, not a source token.
- Options
- Source language and resource settings. Hard byte/depth ceilings bound allocation.
- Original
AstArtifact - The pinned original-stage
AST.tlacontents returned in memory. This artifact precedes identifier fixing and generation; it does not certify an enclosing module, a model, a header CRC, or a filesystem write. - Parsed
- Complete source grammar result; translation acceptance is not implied.
- Process
Translation - Admitted process storage context, never an evaluated process-domain claim.
- Source
Option Argument - One original source option word, including its exact UTF-8 extent.
- Source
Option Declaration - First deciding reference-recognized declaration; later declarations are ignored.
- Translation
- A native generated TLA body, without file checksums or translator map format.
- Translation
Context - Requested settings and the resolved source-option context.
- Translation
Error - A translation failure never carries a partially accepted artifact.
- Translation
Map - An artifact region and its original PlusCal source region.
- Translation
Options - Native translator settings and explicit resource bounds.
- Translation
Warning - A nonfatal normalization observation, never a successful check verdict.
Enums§
- Code
- Stable native PlusCal diagnostic categories.
- Fairness
Option - Pinned translator fairness selection, applied before process normalization.
- Translation
Stage - The stage deciding a translation failure.
Functions§
- algorithm_
checksum_ at - Serialize exact procedure-free algorithm checksum shapes. Expression layout, macros, labels and supported debug locations follow the pinned serializer. Unsupported serialization returns a named diagnostic; translation and rewriting use an optional checksum and proceed without it. Procedure header transfer emulation is intentionally unavailable.
- original_
ast_ at - Returns a bounded normalized original AST using the pinned semantic serializer. Modern procedure/macro ownership and compound locations follow the typed source stages. Historical fields and broader original-stage coverage remain unfinished; availability is not generated-module or model acceptance. No Java or filesystem write occurs, and no translation checksum is returned.
- parse
- Parses a complete standalone algorithm source, rejecting trailing tokens. This certifies source grammar only; translation remains explicitly pending.
- parse_
at - Parses an explicitly selected algorithm region in a surrounding source file.
The region must include the
--algorithm/--fairmarker and exclude enclosing comment delimiters and unrelated TLA+ text. Every selected token is consumed. Returned spans refer to the complete original source, not the selected slice. Parsing runs on a scoped worker with a 16 MiB stack, so the hard recursive depth ceiling does not depend on the caller’s stack size. The worker is joined before returning and never outlives the borrowed input. - resolve_
translation_ options - Resolves supported source translator options before normalization. First source fairness overrides explicit fairness. No malformed, unknown, conflicting or partially applied declaration produces effective settings.
- source_
option_ declaration_ span - Find the reference-style source option header before hiding old output.
- source_
options_ span - Locates the first deciding source declaration using the reference whole-file scan. This performs no comment/string removal. It is a context location, not parsing or artifact admission; malformed declarations are returned too.
- translate
- Translates a bounded current C/P algorithm using the pinned translator’s labels, scoped renaming, macro expansion, process and procedure semantics. Symbolic process domains are translated without evaluating them. Historical modes and generated-operator collisions remain explicit refusals. Complete module name and level analysis belongs to the whole-module API.
- translate_
at - Translates a selected algorithm in original module source. Original byte spans are preserved. Each call joins a 16 MiB scoped worker; the translator never invokes Java or writes files.