Struct molt::types::Exception

pub struct Exception { /* fields omitted */ }

This struct represents the exceptional results of evaluating a Molt script, as used in MoltResult. It is often used as the Err type for other functions in the Molt API, so that these functions can easily return errors when used in the definition of Molt commands.

A Molt command or script can return a normal result, as indicated by MoltResult's Ok variant, or it can return one of a number of exceptional results via Err(Exception). Exceptions bubble up the call stack in the usual way until caught. The different kinds of exceptional result are defined by the ResultCode enum. Client code is primarily concerned with ResultCode::Error exceptions; other exceptions are handled by the interpreter and various control structure commands. Except within application-specific control structure code (a rare bird), non-error exceptions can usually be ignored or converted to error exceptions— and the latter is usually done for you by the interpreter anyway.

Implementations

impl Exception

pub fn is_error(&self) -> bool

Returns true if the exception is an error exception, and false otherwise. In client code, an Exception almost always will be an error; and unless you're implementing an application-specific control structure can usually be treated as an error in any event.

Example

let mut interp = Interp::new();
let input = "throw MYERR \"Error Message\"";

match interp.eval(input) {
   Ok(val) => (),
   Err(exception) => {
       assert!(exception.is_error());
   }
}

pub fn error_code(&self) -> Value

Returns the exception's error code, only if is_error(). exception.

Panics

Panics if the exception is not an error.

pub fn error_info(&self) -> Value

Returns the exception's error info, i.e., the human-readable error stack trace, only if is_error().

Panics

Panics if the exception is not an error.

pub fn error_data(&self) -> Option<&ErrorData>

Gets the exception's ErrorData, if any; the error data is available only when the code() is ResultCode::Error. The error data contains the error's error code and stack trace information.

Example

let mut interp = Interp::new();
let input = "throw MYERR \"Error Message\"";

match interp.eval(input) {
   Ok(val) => (),
   Err(exception) => {
       if let Some(error_data) = exception.error_data() {
           assert_eq!(error_data.error_code(), "MYERR".into());
       }
   }
}

pub fn code(&self) -> ResultCode

Gets the exception's result code.

Example

This example shows catching all of the possible result codes. Except in control structure code, all of these but ResultCode::Return can usually be treated as an error; and the caller of Interp::eval will only see them if the script being called used the return command's -level option (or the Rust equivalent).

let mut interp = Interp::new();
let input = "throw MYERR \"Error Message\"";

match interp.eval(input) {
   Ok(val) => (),
   Err(exception) => {
       match exception.code() {
           ResultCode::Okay => { println!("Got an okay!") }
           ResultCode::Error => { println!("Got an error!") }
           ResultCode::Return => { println!("Got a return!") }
           ResultCode::Break => { println!("Got a break!")  }
           ResultCode::Continue => { println!("Got a continue!")  }
           ResultCode::Other(n) => { println!("Got an other {}", n)  }
       }
   }
}

pub fn value(&self) -> Value

Gets the exception's value, i.e., the explicit return value or the error message. In client code, this will almost always be an error message.

Example

This example shows catching all of the possible result codes. Except in control structure code, all of these but ResultCode::Return can usually be treated as an error; and the caller of Interp::eval will only see them if the script being called used the return command's -level option (or the Rust equivalent).

let mut interp = Interp::new();
let input = "throw MYERR \"Error Message\"";

match interp.eval(input) {
   Ok(val) => (),
   Err(exception) => {
       assert_eq!(exception.value(), "Error Message".into());
   }
}

pub fn level(&self) -> usize

Gets the exception's level. The "level" code is set by the return command's -level option. See The Molt Book's return page for the semantics. Client code should rarely if ever need to refer to this.

pub fn next_code(&self) -> ResultCode

Gets the exception's "next" code (when code == ResultCode::Return only). The "next" code is set by the return command's -code option. See The Molt Book's return page for the semantics. Client code should rarely if ever need to refer to this.

pub fn add_error_info(&mut self, line: &str)

Adds a line to the exception's error info, i.e., to its human readable stack trace. This is for use by command definitions that execute a TCL script and wish to add to the stack trace on error as an aid to debugging.

Example

let mut interp = Interp::new();
let input = "throw MYERR \"Error Message\"";
assert!(my_func(&mut interp, &input).is_err());

fn my_func(interp: &mut Interp, input: &str) -> MoltResult {
    // Evaluates the input; on error, adds some error info and rethrows.
    match interp.eval(input) {
       Ok(val) => Ok(val),
       Err(mut exception) => {
           if exception.is_error() {
               exception.add_error_info("in rustdoc example");
           }
           Err(exception)
       }
    }
}

Panics

Panics if the exception is not an error exception.

pub fn molt_err(msg: Value) -> Self

Creates an Error exception with the given error message. This is primarily intended for use by the molt_err! macro, but it can also be used directly.

Example

let ex = Exception::molt_err("error message".into());
assert!(ex.is_error());
assert_eq!(ex.value(), "error message".into());

pub fn molt_err2(error_code: Value, msg: Value) -> Self

Creates an Error exception with the given error code and message. An error code is a MoltList that indicates the nature of the error. Standard TCL uses the error code to flag specific arithmetic and I/O errors; most other errors have the code NONE. At present Molt doesn't define any error codes other than NONE, so this method is primarily for use by the throw command; but use it if your code needs to provide an error code.

Example

let ex = Exception::molt_err2("MYERR".into(), "error message".into());
assert!(ex.is_error());
assert_eq!(ex.error_code(), "MYERR".into());
assert_eq!(ex.value(), "error message".into());

pub fn molt_return(value: Value) -> Self

Creates a Return exception, with the given return value. Return Value::empty() if there is no specific result.

This method is primarily for use by the return command, and should rarely if ever be needed in client code. If you fully understand the semantics of the return and catch commands, you'll understand what this does and when you would want to use it. If you don't, you almost certainly don't need it.

pub fn molt_return_ext(
    value: Value,
    level: usize,
    next_code: ResultCode
) -> Self

Creates an extended Return exception with the given return value, -level, and -code. Return Value::empty() if there is no specific result.

It's an error if level == 0 and next_code == Okay; that's Ok(value) rather than an exception.

This method is primarily for use by the return command, and should rarely if ever be needed in client code. If you fully understand the semantics of the return and catch commands, you'll understand what this does and when you would want to use it. If you don't, you almost certainly don't need it.

pub fn molt_return_err(
    msg: Value,
    level: usize,
    error_code: Option<Value>,
    error_info: Option<Value>
) -> Self

Creates an exception that will produce an Error exception with the given data, either immediately or some levels up the call chain. This is usually used to rethrow an existing error.

This method is primarily for use by the return command, and should rarely if ever be needed in client code. If you fully understand the semantics of the return and catch commands, you'll understand what this does and when you would want to use it. If you don't, you almost certainly don't need it.

pub fn molt_break() -> Self

Creates a Break exception.

This method is primarily for use by the break command, and should rarely if ever be needed in client code. If you fully understand the semantics of the return and catch commands, you'll understand what this does and when you would want to use it. If you don't, you almost certainly don't need it.

pub fn molt_continue() -> Self

Creates a Continue exception.

This method is primarily for use by the continue command, and should rarely if ever be needed in client code. If you fully understand the semantics of the return and catch commands, you'll understand what this does and when you would want to use it. If you don't, you almost certainly don't need it.

Trait Implementations

impl Clone for Exception

fn clone(&self) -> Exception

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Exception

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

Formats the value using the given formatter.

impl Eq for Exception

impl PartialEq<Exception> for Exception

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl StructuralEq for Exception

impl StructuralPartialEq for Exception