Struct SymbolPath 

pub struct SymbolPath {
    pub path: SmallVec<[SymbolNameComponent; 3]>,
}

This type is a custom [Attribute] for [Symbol] references.

A SymbolPath is represented much like a filesystem path, i.e. as a vector of components. Each component refers to a distinct Symbol that must be resolvable, the details of which depends on what style of path is used.

Similar to filesystem paths, there are two types of paths supported:

• Unrooted (i.e. relative) paths. These are resolved from the nearest parent SymbolTable, and must terminate with SymbolNameComponent::Leaf.
• Absolute paths. The resolution rules for these depends on what the top-level operation is as reachable from the containing operation, described in more detail below. These paths must begin with SymbolNameComponent::Root.

NOTE: There is no equivalent of the . or .. nodes in a filesystem path in symbol paths, at least at the moment. Thus there is no way to refer to symbols some arbitrary number of parents above the current SymbolTable, they must be resolved to absolute paths by the frontend for now.

Symbol Resolution

Relative paths, as mentioned above, are resolved from the nearest parent SymbolTable; if no SymbolTable is present, an error will be raised.

Absolute paths are relatively simple, but supports two use cases, based on the top-level operation reachable from the current operation, i.e. the operation at the top of the ancestor tree which has no parent:

1. If the top-level operation is an anonymous SymbolTable (i.e. it is not also a Symbol), then that SymbolTable corresponds to the global (root) namespace, and symbols are resolved recursively from there.
2. If the top-level operation is a named SymbolTable (i.e. it is also a Symbol), then it is presumed that the top-level operation is defined in the global (root) namespace, even though we are unable to reach the global namespace directly. Thus, the symbol we’re trying to resolve must be a descendant of the top-level operation. This implies that the symbol path of the top-level operation must be a prefix of path.

We support the second style to allow for working with more localized chunks of IR, when no symbol references escape the top-level SymbolTable. This is mostly useful in testing scenarios.

Symbol resolution of absolute paths will fail if:

• The top-level operation is not a SymbolTable
• The top-level operation is a Symbol whose path is not a prefix of path
• We are unable to resolve any component of the path, starting from the top-level
• Any intermediate symbol in the path refers to a Symbol which is not also a SymbolTable

Fields

path: SmallVec<[SymbolNameComponent; 3]>

The underlying components of the symbol name (alternatively called the symbol path).

Implementations

impl SymbolPath

pub fn new<I>(components: I) -> Result<Self, InvalidSymbolPathError>

where I: IntoIterator<Item = SymbolNameComponent>,

pub fn from_masm_function_id(id: FunctionIdent) -> Self

Converts a FunctionIdent representing a fully-qualified Miden Assembly procedure path, to it’s equivalent SymbolPath representation.

Example

use midenc_hir::{SymbolPath, SymbolNameComponent, FunctionIdent};

let id = FunctionIdent {
    module: "intrinsics::mem".into(),
    function: "load_felt_unchecked".into(),
};
assert_eq!(
    SymbolPath::from_masm_function_id(id),
    SymbolPath::from_iter([
        SymbolNameComponent::Root,
        SymbolNameComponent::Component("intrinsics".into()),
        SymbolNameComponent::Component("mem".into()),
        SymbolNameComponent::Leaf("load_felt_unchecked".into()),
    ])
);

pub fn from_masm_module_id(id: &str) -> Self

Converts a str representing a fully-qualified Miden Assembly module path, to it’s equivalent SymbolPath representation.

Example

use midenc_hir::{SymbolPath, SymbolNameComponent};

assert_eq!(
    SymbolPath::from_masm_module_id("intrinsics::mem"),
    SymbolPath::from_iter([
        SymbolNameComponent::Root,
        SymbolNameComponent::Component("intrinsics".into()),
        SymbolNameComponent::Component("mem".into()),
    ])
);

pub fn name(&self) -> SymbolName

Returns the leaf component of the symbol path

pub fn set_name(&mut self, name: SymbolName)

Set the value of the leaf component of the path, or append it if not yet present

pub fn namespace(&self) -> Option<SymbolName>

Returns the first non-root component of the symbol path, if the path is absolute

pub fn to_library_path(&self) -> LibraryPath

Derive a Miden Assembly LibraryPath from this symbol path

pub fn is_absolute(&self) -> bool

Returns true if this symbol name is fully-qualified

pub fn has_parent(&self) -> bool

Returns true if this symbol name is nested

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

Returns true if self is a prefix of other, i.e. other is a further qualified symbol reference.

NOTE: If self and other are equal, self is considered a prefix. The caller should check if the two references are identical if they wish to distinguish the two cases.

pub fn is_prefixed_by(&self, prefix: &[SymbolNameComponent]) -> bool

Returns true if prefix is a prefix of self, i.e. self is a further qualified symbol reference.

NOTE: If self and prefix are equal, prefix is considered a valid prefix. The caller should check if the two references are identical if they wish to distinguish the two cases.

pub fn components( &self, ) -> impl ExactSizeIterator<Item = SymbolNameComponent> + '_

Returns an iterator over the path components of this symbol name

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

Get the parent of this path, i.e. all but the last component

pub fn without_leaf(&self) -> Cow<'_, SymbolPath>

Get the portion of this path without the Leaf component, if present.

Trait Implementations

impl Clone for SymbolPath

fn clone(&self) -> SymbolPath

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SymbolPath

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

Formats the value using the given formatter.

impl Display for SymbolPath

Print symbol path according to Wasm Component Model rules, i.e.:

PATH ::= NAMESPACE ":" PACKAGE PACKAGE_PATH? VERSION?

NAMESPACE ::= SYMBOL
PACKAGE ::= SYMBOL (":" SYMBOL)*
PACKAGE_PATH ::= ("/" SYMBOL)+
VERSION ::= "@" VERSION_STRING

The first component of an absolute path (ignoring the Root node) is expected to be the package name, i.e. the NAMESPACE ":" PACKAGE part as a single symbol.

The first component of a relative path is expected to be either Component or Leaf

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

Formats the value using the given formatter.

impl From<&SymbolPath> for Callable

fn from(value: &SymbolPath) -> Self

Converts to this type from the input type.

impl From<SymbolPath> for Callable

fn from(value: SymbolPath) -> Self

Converts to this type from the input type.

impl FromIterator<SymbolNameComponent> for SymbolPath

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = SymbolNameComponent>,

Creates a value from an iterator.

impl Hash for SymbolPath

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SymbolPath

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for SymbolPath

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 PartialOrd for SymbolPath

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PrettyPrint for SymbolPath

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 TryFrom<&SymbolPath> for ComponentId

type Error = InvalidComponentIdError

The type returned in the event of a conversion error.

fn try_from(path: &SymbolPath) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for SymbolPath