Enum RuntimeError

#[non_exhaustive]
pub enum RuntimeError {
    Nil {
        access_origin: Origin,
    },
    NonSingleton {
        access_origin: Origin,
        actual: usize,
    },
    ShortSlice {
        access_origin: Origin,
        minimum: usize,
        actual: usize,
    },
    OutOfBounds {
        access_origin: Origin,
        index: usize,
        length: usize,
    },
    ReadOnly {
        access_origin: Origin,
        data_origin: Origin,
    },
    WriteOnly {
        access_origin: Origin,
        data_origin: Origin,
    },
    ReadToWrite {
        access_origin: Origin,
        borrow_origin: Origin,
    },
    WriteToRead {
        access_origin: Origin,
        borrow_origin: Origin,
    },
    WriteToWrite {
        access_origin: Origin,
        borrow_origin: Origin,
    },
    Utf8Decoding {
        access_origin: Origin,
        cause: Box<Utf8Error>,
    },
    BorrowLimit {
        access_origin: Origin,
        limit: usize,
    },
    TypeMismatch {
        access_origin: Origin,
        data_type: &'static TypeMeta,
        expected_types: Vec<&'static TypeMeta>,
    },
    DowncastStatic {
        access_origin: Origin,
    },
    UpcastResult {
        access_origin: Origin,
        cause: Arc<dyn StdError + Send + Sync + 'static>,
    },
    NumberCast {
        access_origin: Origin,
        from: &'static TypeMeta,
        to: &'static TypeMeta,
        cause: NumberCastCause,
        value: Arc<dyn NumValue>,
    },
    NumericOperation {
        invoke_origin: Origin,
        kind: NumericOperationKind,
        lhs: (&'static TypeMeta, Arc<dyn NumValue>),
        rhs: Option<(&'static TypeMeta, Arc<dyn NumValue>)>,
        target: &'static TypeMeta,
    },
    RangeCast {
        access_origin: Origin,
        from: Range<usize>,
        to: &'static str,
    },
    MalformedRange {
        access_origin: Origin,
        start_bound: usize,
        end_bound: usize,
    },
    PrimitiveParse {
        access_origin: Origin,
        from: String,
        to: &'static TypeMeta,
        cause: Arc<dyn StdError + Send + Sync + 'static>,
    },
    ArityMismatch {
        invocation_origin: Origin,
        function_origin: Origin,
        parameters: usize,
        arguments: usize,
    },
    UndefinedOperator {
        access_origin: Origin,
        receiver_origin: Option<Origin>,
        receiver_type: &'static TypeMeta,
        operator: OperatorKind,
    },
    UnknownField {
        access_origin: Origin,
        receiver_origin: Origin,
        receiver_type: &'static TypeMeta,
        field: String,
    },
    FormatError {
        access_origin: Origin,
        receiver_origin: Origin,
    },
    UnknownPackage {
        access_origin: Origin,
        name: &'static str,
        version: &'static str,
    },
    Interrupted {
        origin: Origin,
    },
    StackOverflow {
        origin: Origin,
    },
}

Represents any error that may occur during the evaluation of Script code.

This object implements the Debug and Display traits. The Display implementation provides a brief description of the underlying error.

However, it is recommended to use the RuntimeError::display function instead, as it renders the script’s source code and annotates it with detailed error messages.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Nil

The script code attempts to access Nil data.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

NonSingleton

The script code attempts to access an object representing an array with zero or more than one element.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

actual: usize

The actual length of the array.

ShortSlice

The script array is too short and cannot be interpreted as an array with the requested number of elements.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

minimum: usize

The required length of the array.

actual: usize

The actual length of the array.

OutOfBounds

The script code attempts to index into an array or string, but the index is out of bounds.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

index: usize

The requested index for the array or string.

length: usize

The actual length of the array or string.

ReadOnly

The script code attempts to mutate an object that only provides read-only access.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

data_origin: Origin

The range in Rust or Script source code where the data was created.

WriteOnly

The script code attempts to read an object that only provides mutation access.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

data_origin: Origin

The range in Rust or Script source code where the data was created.

ReadToWrite

The script code attempts to mutate an object that is currently borrowed for reading.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

borrow_origin: Origin

The range in Rust or Script source code where the data was previously borrowed.

WriteToRead

The script code attempts to read an object that is currently borrowed for writing.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

borrow_origin: Origin

The range in Rust or Script source code where the data was previously borrowed.

WriteToWrite

The script code attempts to borrow data for mutation more than once at a time.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

borrow_origin: Origin

The range in Rust or Script source code where the data was previously borrowed.

Utf8Decoding

The script attempts to decode a byte array that is not a valid UTF-8 encoding.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

cause: Box<Utf8Error>

An error that occurred during UTF-8 decoding.

BorrowLimit

The script attempts to borrow data too many times simultaneously.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

limit: usize

The maximum number of allowed simultaneous active borrows.

TypeMismatch

The script attempts to use a data object as an argument for a function or an operator, but the data type does not meet the requirements.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

data_type: &'static TypeMeta

The type of the data object being provided as an argument.

expected_types: Vec<&'static TypeMeta>

A list of expected types acceptable for this operation.

DowncastStatic

The script attempts to dereference a data object, but the data object does not live long enough.

Fields

access_origin: Origin

The range in Rust or Script source code where the data was accessed.

UpcastResult

The script calls a Rust function that results in Result::Err.

Fields

access_origin: Origin

The range in Rust or Script source code where the function was invoked.

cause: Arc<dyn StdError + Send + Sync + 'static>

The inner value of the Err variant.

NumberCast

The script attempts to cast one numeric type into another, but the conversion is not possible for the specified source number value and the requested destination type.

Fields

access_origin: Origin

The range in Rust or Script source code where the numeric object was accessed for conversion.

from: &'static TypeMeta

The source type of the value from which the conversion was requested.

to: &'static TypeMeta

The destination type into which the source number should be converted.

cause: NumberCastCause

The cause of the failure.

value: Arc<dyn NumValue>

The source numeric value. This object implements Display.

NumericOperation

The script attempts to perform an operation between two primitive numeric values (or on a single numeric value), but the operation results in an error due to specific reasons (e.g., numeric overflow).

Fields

invoke_origin: Origin

The range in Rust or Script source code where the operation was requested.

kind: NumericOperationKind

The type of numeric operation.

lhs: (&'static TypeMeta, Arc<dyn NumValue>)

The left-hand side of the operation.

rhs: Option<(&'static TypeMeta, Arc<dyn NumValue>)>

The right-hand side of the operation. If omitted, the operation has only one argument.

target: &'static TypeMeta

The numeric type expected to represent the result of the operation.

RangeCast

The script attempts to cast a Range object into another range type (e.g., 100..200 into 100..=199), but such casting is not possible due to unsatisfied bounds.

Fields

access_origin: Origin

The range in Rust or Script source code where the casting was requested.

from: Range<usize>

The original value of the range from which the casting was supposed to happen.

to: &'static str

The name of the target range type.

MalformedRange

The script attempts to use a malformed range (e.g., 200..100).

Fields

access_origin: Origin

The range in Rust or Script source code where the range was accessed.

start_bound: usize

The lower bound of the Range.

end_bound: usize

The upper bound of the Range.

PrimitiveParse

The script attempts to parse a string into a primitive type, but the string is malformed and cannot be interpreted as the requested primitive type.

Fields

access_origin: Origin

The range in Rust or Script source code where the string was accessed for parsing.

from: String

The content of the string being parsed.

to: &'static TypeMeta

The primitive type into which the string was supposed to be parsed.

cause: Arc<dyn StdError + Send + Sync + 'static>

A description of the parse error.

ArityMismatch

The script attempts to call a function with an incorrect number of arguments, either too few or too many.

Fields

invocation_origin: Origin

The range in Rust or Script source code where the function was invoked.

function_origin: Origin

The range in Rust or Script source code where the function was declared.

parameters: usize

The expected number of parameters for the function.

arguments: usize

The actual number of arguments that were passed during the invocation.

UndefinedOperator

The script attempts to apply an operator to an object, but the object’s type does not support this operator.

Fields

access_origin: Origin

The range in Rust or Script source code where the operator was applied.

receiver_origin: Option<Origin>

The range in Rust or Script source code where the object was created. If omitted, the object instance has not been created yet (e.g., the operator is an instantiation operator).

receiver_type: &'static TypeMeta

The type of the object to which the operator was applied.

operator: OperatorKind

The type of operator.

UnknownField

The script attempts to access a field of an object, but the object does not have the specified field.

Fields

access_origin: Origin

A Rust or Script source code range, where the field was accessed.

receiver_origin: Origin

The range in Rust or Script source code where the field was accessed.

receiver_type: &'static TypeMeta

The type of the receiver object.

field: String

The name of the field.

FormatError

The script attempts to format a data object using the Debug or Display implementations, but the formatter returns an error.

Fields

access_origin: Origin

The range in Rust or Script source code where the object was accessed for formatting.

receiver_origin: Origin

The origin of the receiver object.

UnknownPackage

The script attempts to access a package that is not fully registered (e.g., the export system has been switched to a shallow mode).

Fields

access_origin: Origin

The range in Rust or Script source code where the package metadata was accessed.

name: &'static str

The name of the package.

version: &'static str

The version of the package.

Interrupted

The script evaluation has been interrupted by the thread’s runtime hook.

Fields

origin: Origin

The range in Rust or Script source code where the interruption occurred.

StackOverflow

The script has been interrupted because the interpreter’s memory stack for the thread overflowed.

Fields

origin: Origin

The range in Rust or Script source code where the interruption occurred.

Implementations

impl RuntimeError

pub fn display<'a>( &self, resolver: &'a impl ModuleTextResolver, ) -> impl Display + 'a

Returns a printable object that renders the script’s source code and annotates it with error messages describing the underlying error object and pointing to the source code location(s) where the error occurred.

This function provides a canonical way to print end-user-facing script evaluation error messages.

The resolver parameter specifies an object through which the returned printer accesses the ModuleText.

In a multi-module environment, a RuntimeError may occur in any of these modules and could potentially relate to several scripts. The resolver allows the printer to access their source code texts when formatting the message.

If your runtime configuration consists of just one script module, or if you are confident that the modules are semantically isolated from each other (by default, modules are isolated), you can directly use the ModuleText of the script module as the resolver argument.

pub fn primary_origin(&self) -> &Origin

Returns the Rust or Script source code range where the error occurred.

pub fn secondary_origin(&self) -> Option<&Origin>

Returns an additional Rust or Script source code range that hints at an extra location related to the cause of the error.

For example, the ReadToWrite error variant includes an additional location that indicates the previous borrowing site.

Most error variants do not have an extra location, and in such cases, this function will return None.

pub fn primary_description(&self) -> String

Returns an error message string related to the primary_origin.

This function returns the same message string that you would get by formatting RuntimeError using the Display implementation.

pub fn secondary_description(&self) -> String

Returns an error message string related to the secondary_origin.

If the error variant does not have an extra location, this function returns an empty string.

pub fn summary(&self) -> String

Returns a detailed summary of this error.

This message is the same one that would be printed in the footer of the RuntimeError::display object.

Trait Implementations

impl Clone for RuntimeError

fn clone(&self) -> RuntimeError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RuntimeError

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

Formats the value using the given formatter.

impl Display for RuntimeError

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

Formats the value using the given formatter.

impl Error for RuntimeError

fn source(&self) -> Option<&(dyn StdError + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.