README- UEvalError
- UModule
- UValue
- Veval
- Vexec
#errors package
All error and source-location types used across the Starlark interpreter. Import connect0459/starlark/errors for EvalError, SyntaxError, ResolveError, Position, Binding, CallStack, and CallFrame.
exec_file wraps SyntaxError and ResolveError into EvalError before returning, so most callers only need to handle EvalError.
#Key types
| Type | Description |
|---|---|
| EvalError | Runtime error with message, call stack, and optional cause |
| SyntaxError | Lexer / parser error |
| ResolveError | Name-resolution error |
| Position | Source location (filename, 1-based line, 1-based column) |
| Binding | Local variable name + definition position (debugger API) |
| CallStack | Snapshot of the call stack (ordered outermost → innermost) |
| CallFrame | Single frame: function name + call-site position |
#Quick start
Constructing error values directly:
///|
test {
let pos = @errors.Position::new("build.star", 5, 3)
assert_eq(pos.filename(), "build.star")
assert_eq(pos.line(), 5)
assert_eq(pos.col(), 3)
assert_eq(pos.to_string(), "build.star:5:3")
}///|
test {
let err = @errors.EvalError::simple("something went wrong")
assert_eq(err.msg(), "something went wrong")
assert_true(err.cause() is None)
}///|
test {
let pos = @errors.Position::new("x.star", 1, 1)
let frame = @errors.CallFrame::new("my_func", pos)
let stack = @errors.CallStack::new([frame])
assert_eq(stack.length(), 1)
match stack.at(0) {
Some(f) => assert_eq(f.name(), "my_func")
None => fail("expected frame")
}
}Errors returned from @eval.exec_file include source location information. Runtime errors carry a structured call stack; parse and resolve failures embed the position in the error message string. See @eval for usage in execution context.
#API reference
#EvalError
| Method | Returns | Description |
|---|---|---|
| EvalError::simple(String) | EvalError | Construct with no position (for host code) |
| EvalError::with_stack(String, CallStack) | EvalError | Construct with a call stack |
| EvalError::with_cause(String, CallStack, EvalError) | EvalError | Construct wrapping an inner cause |
| msg() | String | Error message |
| to_string() | String | Error message string (same as msg()) |
| backtrace() | String | Formatted call stack ending with "Error: msg" |
| call_stack() | CallStack | The captured call stack as structured frames |
| cause() | EvalError? | The wrapped inner error, if this error chains one |
backtrace() always ends the output with Error: <msg> (or Error in <builtin>: <msg> when the innermost frame is a built-in). This format is intentional — the mbt CLI uses backtrace() directly to display errors, so the Error: prefix appears in all CLI output. starlark-go omits the prefix and prints the message directly; the difference is a deliberate quality-of-life choice.
#SyntaxError and ResolveError
Both carry a Position and a message; exec_file wraps these into EvalError before returning.
| Method | Returns | Description |
|---|---|---|
| SyntaxError::new(Position, String) | SyntaxError | Construct from a position and message (kind Other) |
| SyntaxError::with_kind(Position, String, SyntaxErrorKind) | SyntaxError | Construct with an explicit kind |
| ResolveError::new(Position, String) | ResolveError | Construct from a position and message |
| msg() | String | Error message |
| pos() | Position | Source position |
| SyntaxError::kind() | SyntaxErrorKind | Structural classification of the error |
| to_string() | String | "<file>:<line>:<col>: <msg>" |
SyntaxErrorKind classifies a SyntaxError by structural cause so consumers (such as the REPL's continuation detector) can branch on the kind instead of matching the English message text:
| Variant | Meaning |
|---|---|
| UnexpectedEof | Input ended while a construct was still open (e.g. a compound opener or unclosed bracket) — may complete with more input |
| UnterminatedString | A string literal was not closed before end of input — may complete with more input |
| Other | Any other syntax error — genuinely invalid input |
#Position
| Method | Returns | Description |
|---|---|---|
| Position::new(String, Int, Int) | Position | Construct from filename, line, column |
| filename() | String | Source file name |
| line() | Int | 1-based line number |
| col() | Int | 1-based column (0 = unknown) |
| is_valid() | Bool | true if line > 0 |
| is_before(Position) | Bool | Positional comparison |
| to_string() | String | "<file>:<line>:<col>" |
#Binding
A local variable name with its definition position; used by the debugger API.
| Method | Returns | Description |
|---|---|---|
| Binding::new(String, Position) | Binding | Construct from a name and position |
| name() | String | Variable name |
| pos() | Position | Declaration position in source |
#CallStack and CallFrame
| Method | Returns | Description |
|---|---|---|
| CallStack::new(Array[CallFrame]) | CallStack | Construct from frames (0 = outermost) |
| length() | Int | Number of frames |
| at(Int) | CallFrame? | Frame at index; None if out of range |
| pop() | CallFrame? | Remove and return the innermost frame |
| to_string() | String | Human-readable backtrace |
| CallFrame::new(String, Position) | CallFrame | Construct from a name and call-site position |
| name() | String | Function name at this frame |
| pos() | Position | Call-site position |
Binding
pub struct Binding {
// private fields
}A local variable name together with its definition position; used by the
debugger API.
Binding::name
Returns the variable name.
Returns the name string of this binding.
Binding::new
Creates a Binding with the given name and definition position.
Parameters:
- name : The variable name.
- pos : The source position where the variable is defined.
Returns a new Binding value.
CallFrame
pub struct CallFrame {
// private fields
}A single frame in a Starlark call stack: the function name and the source
position of the call site within that function.
CallFrame::name
Returns the function name for this frame.
Returns the function name string.
CallFrame::new
Creates a CallFrame with the given function name and call-site position.
Parameters:
- name : The function name for this frame.
- pos : The source position of the call site within the function.
Returns a new CallFrame value.
CallStack
pub struct CallStack {
// private fields
}An ordered snapshot of call frames, outermost first, innermost last.
CallStack::at
Returns the frame at index i (0 = outermost), or None if out of range.
Parameters:
- self : The call stack to index into.
- i : The zero-based index of the frame to retrieve.
Returns Some(frame) if i is in range, None otherwise.
CallStack::length
Returns the number of frames in the stack.
Returns the frame count as an Int.
CallStack::new
Creates a CallStack from a pre-built array of frames.
Parameters:
- frames : An array of CallFrame values, outermost first.
Returns a new CallStack wrapping the given frames.
CallStack::pop
Removes and returns the innermost (last) frame, or None if the stack is
empty.
Returns Some(frame) with the removed innermost frame, or None if empty.
EvalError
pub struct EvalError {
// private fields
}A runtime evaluation error carrying a message, a call-stack snapshot, and
an optional inner cause for load-error chaining.
EvalError::backtrace
Returns a formatted traceback string ending with "Error: msg". Strips a
trailing <builtin> frame and appends it as " in name" instead.
Returns the full backtrace string including the error message.
EvalError::call_stack
Returns the call-stack snapshot captured when this error was raised.
Returns the CallStack recorded at the point of the error; empty for
errors created with simple.
EvalError::cause
Returns the inner cause error, if this error was created with
with_cause.
Returns Some(inner) if a cause was set, None otherwise.
EvalError::msg
Returns the error message string.
Returns the message string of this error.
EvalError::simple
Creates an EvalError with only a message and an empty call stack.
Parameters:
- msg : The human-readable error message.
Returns a new EvalError with an empty call stack and no cause.
EvalError::to_string
Returns just the error message (same as msg); implements the Show
trait.
Returns the error message string.
EvalError::with_cause
Creates an EvalError that wraps an inner cause, used to chain load
errors so the original inner backtrace is accessible.
Parameters:
- msg : The human-readable error message for the outer error.
- call_stack : The call-stack snapshot at the point of the outer error.
- cause : The inner EvalError being wrapped.
Returns a new EvalError that chains to the given cause.
EvalError::with_stack
Creates an EvalError with a message and a call-stack snapshot.
Parameters:
- msg : The human-readable error message.
- call_stack : The call-stack snapshot at the point of the error.
Returns a new EvalError with the given message and stack, and no cause.
Position
pub struct Position {
// private fields
}A source location using 1-based line and column numbers, matching
starlark-go's syntax.Position convention. Line 0 means unknown.
Position::col
Returns the 1-based column number, or 0 if the position is unknown.
Returns the column number as an Int.
Position::filename
Returns the filename component of this position.
Returns the source file name string.
Position::is_before
Returns true if this position precedes other in the same source file.
Parameters:
- self : The position to compare from.
- other : The position to compare against.
Returns true if self comes before other by line then column.
Position::is_valid
Returns true if the position carries a meaningful line number.
Returns true when line > 0, false otherwise.
Position::line
Returns the 1-based line number, or 0 if the position is unknown.
Returns the line number as an Int.
Position::new
Creates a Position. Use line=0 to represent an unknown location.
Parameters:
- filename : The source file name.
- line : The 1-based line number, or 0 for unknown.
- col : The 1-based column number, or 0 for unknown.
Returns a new Position value.
ResolveError
pub struct ResolveError {
// private fields
}A name-resolution error with a source position and a human-readable message.
ResolveError::msg
Returns the human-readable error message.
Returns the error message string.
ResolveError::new
Creates a ResolveError at pos with message msg.
Parameters:
- pos : The source position where the error was detected.
- msg : The human-readable error message.
Returns a new ResolveError value.
ResolveError::pos
Returns the source position where the resolve error was detected.
Returns the Position associated with this error.
ResolveError::to_string
Formats the error as "pos: msg".
Returns the formatted error string.
SyntaxError
pub struct SyntaxError {
// private fields
}A parse-time error with a source position and a human-readable message.
SyntaxError::kind
Returns the structural classification of the error.
Returns the SyntaxErrorKind associated with this error.
SyntaxError::msg
Returns the human-readable error message.
Returns the error message string.
SyntaxError::new
Creates a SyntaxError at pos with message msg and kind Other.
Parameters:
- pos : The source position where the error was detected.
- msg : The human-readable error message.
Returns a new SyntaxError value.
SyntaxError::pos
Returns the source position where the syntax error was detected.
Returns the Position associated with this error.
SyntaxError::to_string
Formats the error as "pos: msg".
Returns the formatted error string.
SyntaxError::with_kind
Creates a SyntaxError at pos with message msg and an explicit kind.
Parameters:
- pos : The source position where the error was detected.
- msg : The human-readable error message.
- kind : The structural classification of the error.
Returns a new SyntaxError value.
SyntaxErrorKind
Classifies a SyntaxError so consumers can branch on the structural cause
instead of matching the English message text. UnexpectedEof and
UnterminatedString mark input that may become valid with more lines (used
by the REPL to request a continuation); every other error is Other.
SyntaxErrorKind::not_equal
Source Files
Install
Download zipThe Starlark configuration language, implemented in Moonbit
starlarkinterpreter
Apache-2.0
Updated 9 hours ago
87 downloadsDependencies
- moonbitlang/x0.5.5