Struct Module 

pub struct Module { /* private fields */ }

The abstract syntax tree for a single Miden Assembly module.

All module kinds share this AST representation, as they are largely identical. However, the ModuleKind dictates how the parsed module is semantically analyzed and validated.

Implementations

impl Module

Constants

pub const FILE_EXTENSION: &'static str = "masm"

File extension for a Assembly Module.

pub const ROOT: &'static str = "mod"

Name of the root module.

pub const ROOT_FILENAME: &'static str = "mod.masm"

File name of the root module.

impl Module

Construction

pub fn new(kind: ModuleKind, path: impl AsRef<Path>) -> Self

Creates a new Module with the specified kind and fully-qualified path, e.g. std::math::u64.

pub fn new_kernel() -> Self

An alias for creating the default, but empty, #kernel Module.

pub fn new_executable() -> Self

An alias for creating the default, but empty, $exec Module.

pub fn with_span(self, span: SourceSpan) -> Self

Specifies the source span in the source file in which this module was defined, that covers the full definition of this module.

pub fn set_path(&mut self, path: impl AsRef<Path>)

Sets the Path for this module

pub fn set_parent(&mut self, ns: impl AsRef<Path>)

Modifies the path of this module by overriding the portion of the path preceding Self::name, i.e. the portion returned by Self::parent.

See PathBuf::set_parent for details.

pub fn set_docs(&mut self, docs: Option<Span<String>>)

Sets the documentation for this module

pub fn set_span(&mut self, span: SourceSpan)

Like Module::with_span, but does not require ownership of the Module.

pub fn take_items(&mut self) -> Vec<Item>

Takes all items from this module, clearing the name index. Used by the linker to consume module contents.

pub fn declare_submodule( &mut self, name: Ident, visibility: Visibility, ) -> Result<(), SemanticAnalysisError>

Declares that this module has a submodule named name, with the specified visibility.

This returns an error if it conflicts with a previous declaration (either a previous submodule declaration, or an imported symbol name).

pub fn declare_extern_package( &mut self, name: Ident, ) -> Result<(), SemanticAnalysisError>

Declares that this module has a dependency on the library target of an external package named name.

This returns an error if it conflicts with a previous extern package declaration.

pub fn define_constant( &mut self, constant: Constant, ) -> Result<(), SemanticAnalysisError>

Defines a constant, raising an error if the constant conflicts with a previous definition

pub fn define_type( &mut self, ty: TypeAlias, ) -> Result<(), SemanticAnalysisError>

Defines a type alias, raising an error if the alias conflicts with a previous definition

pub fn define_enum(&mut self, ty: EnumType) -> Result<(), SemanticAnalysisError>

Define a new enum type ty with visibility

Returns Err if:

• A type alias with the same name as the enum type is already defined
• Two or more variants of the given enum type have the same name
• A constant (including those implicitly defined by variants of other enums in this module) with the same name as any of the variants of the given enum type, is already defined
• The concrete type of the enumeration is not an integral type

pub fn define_procedure( &mut self, procedure: Procedure, _source_manager: Arc<dyn SourceManager>, ) -> Result<(), SemanticAnalysisError>

Defines a procedure, raising an error if the procedure is invalid, or conflicts with a previous definition

pub fn define_import( &mut self, import: Import, ) -> Result<(), SemanticAnalysisError>

Defines an import, raising an error if the import conflicts with a previous declaration.

impl Module

Parsing

pub fn parse( name: impl AsRef<Path>, source_file: Arc<SourceFile>, source_manager: Arc<dyn SourceManager>, ) -> Result<Box<Self>, Report>

Parse a Module, name, of the given ModuleKind, from source_file.

pub fn parse_kernel( source_file: Arc<SourceFile>, source_manager: Arc<dyn SourceManager>, ) -> Result<Box<Self>, Report>

pub fn parser(kind: Option<ModuleKind>) -> ModuleParser

Get a ModuleParser for parsing modules of the provided ModuleKind

If kind is None, then the module kind is inferred as either library or executable based on whether the module contains a begin block. If you wish to parse a kernel module, it must be done explicitly.

impl Module

Metadata

pub fn name(&self) -> &str

Get the name of this specific module, i.e. the last component of the Path that represents the fully-qualified name of the module, e.g. u64 in std::math::u64

pub fn path(&self) -> &Path

Get the fully-qualified name of this module, e.g. std::math::u64

pub fn parent(&self) -> Option<&Path>

Get the path of the parent module of this module, e.g. std::math in std::math::u64

pub fn is_in_namespace(&self, namespace: &Path) -> bool

Returns true if this module belongs to the provided namespace.

pub fn docs(&self) -> Option<Span<&str>>

Get the module documentation for this module, if it was present in the source code the module was parsed from

pub fn kind(&self) -> ModuleKind

Get the type of module this represents:

See ModuleKind for details on the different types of modules.

pub fn set_kind(&mut self, kind: ModuleKind)

Override the type of module this represents.

See ModuleKind for details on what the different types are.

pub fn is_executable(&self) -> bool

Returns true if this module is an executable module.

pub fn is_kernel(&self) -> bool

Returns true if this module is the top-level kernel module.

pub fn is_in_kernel(&self) -> bool

Returns true if this module is a kernel module.

pub fn has_entrypoint(&self) -> bool

Returns true if this module has an entrypoint procedure defined, i.e. a begin..end block.

pub fn advice_map(&self) -> &AdviceMap

Returns a reference to the advice map derived from this module

pub fn constants(&self) -> impl Iterator<Item = &Constant> + '_

Get an iterator over the constants defined in this module.

pub fn constants_mut(&mut self) -> impl Iterator<Item = &mut Constant> + '_

Same as Module::constants, but returns mutable references.

pub fn types(&self) -> impl Iterator<Item = &TypeDecl> + '_

Get an iterator over the types defined in this module.

pub fn types_mut(&mut self) -> impl Iterator<Item = &mut TypeDecl> + '_

Same as Module::types, but returns mutable references.

pub fn procedures(&self) -> impl Iterator<Item = &Procedure> + '_

Get an iterator over the procedures defined in this module.

pub fn procedures_mut(&mut self) -> impl Iterator<Item = &mut Procedure> + '_

Same as Module::procedures, but returns mutable references.

pub fn get_import(&self, name: &str) -> Option<&Import>

Resolves name to an Import within the context of this module.

pub fn get_import_mut(&mut self, name: &str) -> Option<&mut Import>

Same as Module::get_import, but returns a mutable reference to the Import.

pub fn imports(&self) -> impl Iterator<Item = &Import> + '_

Get an iterator over imports in this module.

pub fn imports_mut(&mut self) -> impl Iterator<Item = &mut Import> + '_

Same as Module::imports, but returns mutable references.

pub fn take_imports(&mut self) -> Vec<Import>

Takes all imports from this module.

pub fn required_packages(&self) -> &[Ident]

Get a reference to the set of package identifiers that this module declares a dependency on

This is only reflects explicit extern package declarations of the root project module, not actual requirements, i.e. it is not authoritative.

pub fn submodules(&self) -> &[SubmoduleDecl]

Get a reference to the set of submodule declarations in this module.

pub fn items(&self) -> &[Item]

Get a reference to the items stored in this module

pub fn items_mut(&mut self) -> impl Iterator<Item = &mut Item>

Returns a mutable iterator over the items in this module. Note: does not expose Vec directly to preserve the name_map invariant.

pub fn exported( &self, ) -> impl Iterator<Item = (ItemIndex, QualifiedProcedureName)> + '_

Returns items exported from this module.

Each exported item is represented by its local item index and a fully qualified name.

pub fn procedure_signature(&self, id: ItemIndex) -> Option<&FunctionType>

Gets the type signature for the given ItemIndex, if available.

pub fn get(&self, index: ItemIndex) -> Option<&Item>

Get the item at index in this module’s item table.

The item returned may be either a locally-defined item, or a re-exported item. See Item for details.

pub fn index_of<F>(&self, predicate: F) -> Option<ItemIndex>

where F: FnMut(&Item) -> bool,

Get the ItemIndex for the first item in this module’s item table which returns true for predicate.

pub fn index_of_name(&self, name: &Ident) -> Option<ItemIndex>

Get the ItemIndex for the item whose name is name in this module’s item table, if that item is exported.

Non-exported items can be retrieved by using Module::index_of.

Trait Implementations

impl Clone for Module

fn clone(&self) -> Module

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Module

Debug representation of this module

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

Formats the value using the given formatter.

impl Display for Module

Pretty-printed representation of this module as Miden Assembly text format

NOTE: Delegates to the crate::prettier::PrettyPrint implementation internally

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

Writes this Module as formatted MASM code into the formatter.

The formatted code puts each instruction on a separate line and preserves correct indentation for instruction blocks.

impl Eq for Module

impl Index<ItemIndex> for Module

type Output = Item

The returned type after indexing.

fn index(&self, index: ItemIndex) -> &Self::Output

Performs the indexing (container[index]) operation.

impl IndexMut<ItemIndex> for Module

fn index_mut(&mut self, index: ItemIndex) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl Parse for Module

fn parse( self, _warnings_as_errors: bool, _source_manager: Arc<dyn SourceManager>, ) -> Result<Box<Module>, Report>

Parse (or convert) self into an executable Module.

impl Parse for Box<Module>

fn parse( self, _warnings_as_errors: bool, _source_manager: Arc<dyn SourceManager>, ) -> Result<Box<Module>, Report>

Parse (or convert) self into an executable Module.

impl PartialEq for Module

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PrettyPrint for Module

The pretty-printer for Module

fn render(&self) -> Document

The core of the PrettyPrint functionality.

fn to_pretty_string(&self) -> String

Produce a String containing the results of pretty-printing this object.

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

Pretty-print this object to the given core::fmt::Formatter.

impl Spanned for Module

fn span(&self) -> SourceSpan

impl SymbolTable for &Module

type SymbolIter = IntoIter<LocalSymbol>

The concrete iterator type for the container.

fn symbols(&self, _source_manager: Arc<dyn SourceManager>) -> Self::SymbolIter

Get an iterator over the symbols in this symbol table, using the provided SourceManager to emit errors for symbols which are invalid/unresolvable.

fn checked_symbols( &self, source_manager: Arc<dyn SourceManager>, ) -> Result<Self::SymbolIter, SymbolResolutionError>

Get an iterator over the symbols in this symbol table, returning a structured error if the full symbol set cannot be represented exactly.