Struct PioModule 

pub struct PioModule<T> { /* private fields */ }

The common module records and containers. These explicit facade exports keep ordinary callers out of the component crate paths. One typed PowerIO compiler unit.

T has no PowerIO marker bound. Dynamic parsing and stored JSON register a finite set elsewhere, while Rust applications can use any value here.

Implementations

impl<T> PioModule<T>

pub fn new(value: T) -> PioModule<T>

pub fn into_value(self) -> T

pub const fn value(&self) -> &T

The typed value carried by this module.

pub fn value_mut(&mut self) -> &mut T

The typed value, for an edit in place.

Taking the reference drops the retained source owner and the source map: bytes and RFC 6901 targets that describe the pre-edit value no longer describe what the module carries, so a same format write serializes the value instead of emitting them. Descriptors, diagnostics, and history stay. PioModule::stage_edit is the atomic form, which leaves the module untouched when an edit does not complete.

pub fn diagnostics(&self) -> &[Diagnostic]

Diagnostics produced while acquiring, validating, or deriving the value, in the order they were recorded.

pub const fn producer(&self) -> &Producer

pub fn sources(&self) -> &[SourceDescriptor]

pub fn source_map(&self) -> &[SourceMapEntry]

pub fn history(&self) -> &[HistoryEntry]

pub const fn extensions(&self) -> &BTreeMap<String, Value>

pub const fn source(&self) -> Option<&Source>

pub fn with_producer(self, producer: Producer) -> PioModule<T>

pub fn with_source(self, source: Source) -> PioModule<T>

pub fn sever_source(self) -> PioModule<T>

Drop the retained source owner: the operation that calls this changed the value, so a same format write must serialize the value rather than echo bytes the value no longer matches. Descriptors, diagnostics, and history stay.

pub fn with_diagnostic( self, diagnostic: Diagnostic, ) -> Result<PioModule<T>, Error>

Append a finding, applying the same duplicate identity and span reference checks as PioModule::add_diagnostic. There is no unchecked path onto a module’s records.

pub fn add_source_descriptor( &mut self, source: SourceDescriptor, ) -> Result<(), Error>

pub fn add_source_map_entry( &mut self, entry: SourceMapEntry, ) -> Result<(), Error>

pub fn add_diagnostic(&mut self, diagnostic: Diagnostic) -> Result<(), Error>

pub fn add_history_entry(&mut self, entry: HistoryEntry) -> Result<(), Error>

pub fn insert_extension( &mut self, namespace: impl Into<String>, value: Value, ) -> Result<Option<Value>, Error>

pub fn verify_records(&self) -> Result<(), Error>

Verify cross-record references that cannot be checked by constructors.

pub fn sever_value_targets(&mut self)

Drop records that address the old value: the operation that calls this replaced the value with one of a different kind, so RFC 6901 targets into the old value no longer identify anything. Every diagnostic keeps its code, message, severity, and spans but loses its target, and the source map (whose entries are keyed by such targets) is cleared. Pair this with PioModule::map_value in a kind changing transform so the module still serializes.

pub fn derive_value<U>( self, producer: Producer, history: HistoryEntry, derive: impl FnOnce(T) -> U, ) -> Result<PioModule<U>, Error>

Derive a semantically new value and record the operation that produced it. Source descriptors, diagnostics, prior history, and extensions stay with the module. Locators into the replaced value and retained bytes that no longer encode the result are invalidated.

pub fn try_derive_value<U>( self, producer: Producer, history: HistoryEntry, derive: impl FnOnce(T) -> Result<U, Error>, ) -> Result<PioModule<U>, Error>

Fallible form of PioModule::derive_value.

pub fn try_derive_from_source<U>( self, input_target: &str, source: Source, producer: Producer, history: HistoryEntry, derive: impl FnOnce(T, &Source) -> Result<(U, Vec<Diagnostic>), Error>, ) -> Result<PioModule<U>, Error>

Parse a value that depends on this module and one additional source.

Records that describe the input value are retargeted below input_target. The additional source receives distinct source IDs, becomes the retained source, and is mapped to the new value’s root. This is the shared module operation for readers whose document is not self contained, such as a solution file that must be interpreted against its calculation instance.

Errors

The derived value cannot be built, a target is not an RFC 6901 pointer, or the combined records exceed a module bound.

pub fn map_value<U>(self, convert: impl FnOnce(T) -> U) -> PioModule<U>

Move the value and every module record into another typed module.

pub fn try_map_value<U, E>( self, convert: impl FnOnce(T) -> Result<U, E>, ) -> Result<PioModule<U>, E>

Move the value through a fallible conversion, keeping every module record on success. On failure the conversion’s error is returned and the records are dropped with the consumed value; a caller that must keep the source or findings on the failure route takes them off the module first with PioModule::take_source and the public diagnostics field.

pub fn take_source(&mut self) -> Option<Source>

Take the retained source owner off the module, leaving descriptors, diagnostics, and history in place. The module then reads as constructed in memory until a source is reattached.

pub fn parsed( value: T, source: Source, diagnostics: Vec<Diagnostic>, ) -> Result<PioModule<T>, Error>

Assemble the module a parser returns: the typed value, one descriptor per acquired buffer of the retained source, a coarse root source map, and the reader’s findings.

Errors

A duplicate acquired buffer identity, an invalid buffer name or span, or a finding that fails the record checks of PioModule::add_diagnostic.

impl<T> PioModule<T>

where T: Clone,

pub fn stage_edit(&mut self) -> StagedEdit<'_, T>

Begin an atomic edit of this module’s value and findings.

The candidate uses T::clone; values backed by shared tables retain those tables until StagedEdit::value_mut performs their own copy on write detachment. Dropping the staged edit, or any failed operation on it, leaves this module untouched.

Trait Implementations

impl<T> Clone for PioModule<T>

where T: Clone,

fn clone(&self) -> PioModule<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for PioModule<T>

where T: Debug,

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.