Skip to main content

Crate dive_pluscal

Crate dive_pluscal 

Source
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§

AlgorithmChecksum
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.
InsertedLabel
A generated label associated with its original statement, not a source token.
Options
Source language and resource settings. Hard byte/depth ceilings bound allocation.
OriginalAstArtifact
The pinned original-stage AST.tla contents 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.
ProcessTranslation
Admitted process storage context, never an evaluated process-domain claim.
SourceOptionArgument
One original source option word, including its exact UTF-8 extent.
SourceOptionDeclaration
First deciding reference-recognized declaration; later declarations are ignored.
Translation
A native generated TLA body, without file checksums or translator map format.
TranslationContext
Requested settings and the resolved source-option context.
TranslationError
A translation failure never carries a partially accepted artifact.
TranslationMap
An artifact region and its original PlusCal source region.
TranslationOptions
Native translator settings and explicit resource bounds.
TranslationWarning
A nonfatal normalization observation, never a successful check verdict.

Enums§

Code
Stable native PlusCal diagnostic categories.
FairnessOption
Pinned translator fairness selection, applied before process normalization.
TranslationStage
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/--fair marker 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.