Trait ModuleRead

pub trait ModuleRead<H: TaskHandle>: Identifiable + ModuleReadSealed<H> {
    // Required method
    fn package(&self) -> &'static PackageMeta;

    // Provided methods
    fn is_interrupted(&self) -> bool { ... }
    fn text(&self) -> ModuleText<'_> { ... }
    fn diagnostics(
        &self,
        depth: DiagnosticsDepth,
    ) -> ModuleResult<ModuleDiagnostics> { ... }
    fn symbols(
        &self,
        span: impl ToSpan,
        options: LookupOptions,
    ) -> ModuleResult<Vec<ModuleSymbol>> { ... }
    fn content_origin(&self) -> ScriptOrigin { ... }
    fn compile(&self) -> ModuleResult<ScriptFn> { ... }
}

A set of read functions for the ScriptModule content.

This trait is implemented by both the ModuleReadGuard and ModuleWriteGuard objects. The trait is sealed, meaning it cannot be implemented outside of this crate.

Required Methods

fn package(&self) -> &'static PackageMeta

Returns the metadata object of the script package under which the underlying ScriptModule is being analyzed.

This value is the same as the one provided to the module’s constructor function.

See ScriptPackage for details.

Provided Methods

fn is_interrupted(&self) -> bool

Returns true if the underlying access guard has been revoked.

If the function returns true, it indicates that the guard object needs to be dropped as soon as possible.

fn text(&self) -> ModuleText<'_>

Gets access to the script module’s source code text.

See ModuleText for details.

fn diagnostics( &self, depth: DiagnosticsDepth, ) -> ModuleResult<ModuleDiagnostics>

Computes script module diagnostics (errors and warnings).

The returned ModuleDiagnostics object is a collection of inferred issues that you can iterate through. Using this object, you can also print the source code text annotated with diagnostic messages to the terminal.

The depth numeric argument specifies the level of diagnostic analysis depth. Available values are 1 (syntax errors), 2 (shallow semantic analysis), and 3 (deep semantic analysis). For details, see the DiagnosticsDepth documentation.

fn symbols( &self, span: impl ToSpan, options: LookupOptions, ) -> ModuleResult<Vec<ModuleSymbol>>

Looks up syntax constructions within the specified span (source code range) based on the options filter.

This function allows you to find specific source code constructions (called “symbols”) and then explore their syntax and semantics.

For example, you can find a variable reference in the source code and then determine where this variable was introduced.

The span argument specifies the source code range for the symbol lookup. You can use an absolute Unicode character range like 10..20, a line-column range like Position::new(10, 3)..Position::new(12, 4), or a ScriptOrigin instance.

The options argument specifies the lookup filter. The LookupOptions::default implementation searches for all kinds of language constructions within the specified span, but you can restrict the lookup to a particular set of symbol types.

The function returns a ModuleError::Cursor error if the provided span is not valid for this module.

fn content_origin(&self) -> ScriptOrigin

Returns a range of the source code without the header and footer comments.

// header comment

<content range start>let x = 10;
let y = 20;<content range end>

// footer comment

This range is useful, for example, to determine where to place a new global use foo; import statement in the source code.

Note that the returned ScriptOrigin can be converted into an absolute range of Unicode characters using the to_site_span function: script_origin.to_site_span(&module_guard.text()).

fn compile(&self) -> ModuleResult<ScriptFn>

Compiles the source code into the Ad Astra assembly, making it available for execution. To execute the resulting ScriptFn object, use the ScriptFn::run function.

Source code compilation is typically a fast and robust process. In general, the compiler can compile any source code text, even if it contains diagnostic errors and warnings. However, if the code has diagnostic errors, the correctness of the resulting ScriptFn execution flow is not guaranteed. Running such a ScriptFn object does not result in undefined behavior, as Ad Astra’s virtual machine fully controls the assembly execution. In the worst case, running such an assembly will result in a RuntimeError.

The compiler attempts to compile script code with diagnostic errors in a way that best matches the author’s original intentions. However, it is recommended to avoid running ScriptFn objects in production that have been compiled from script modules with diagnostic errors.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'a, H: TaskHandle> ModuleRead<H> for ModuleReadGuard<'a, H>

impl<'a, H: TaskHandle> ModuleRead<H> for ModuleWriteGuard<'a, H>