🥮 mooncakes.io
README

#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

TypeDescription
EvalErrorRuntime error with message, call stack, and optional cause
SyntaxErrorLexer / parser error
ResolveErrorName-resolution error
PositionSource location (filename, 1-based line, 1-based column)
BindingLocal variable name + definition position (debugger API)
CallStackSnapshot of the call stack (ordered outermost → innermost)
CallFrameSingle 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

MethodReturnsDescription
EvalError::simple(String)EvalErrorConstruct with no position (for host code)
EvalError::with_stack(String, CallStack)EvalErrorConstruct with a call stack
EvalError::with_cause(String, CallStack, EvalError)EvalErrorConstruct wrapping an inner cause
msg()StringError message
to_string()StringError message string (same as msg())
backtrace()StringFormatted call stack ending with "Error: msg"
call_stack()CallStackThe 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.

MethodReturnsDescription
SyntaxError::new(Position, String)SyntaxErrorConstruct from a position and message (kind Other)
SyntaxError::with_kind(Position, String, SyntaxErrorKind)SyntaxErrorConstruct with an explicit kind
ResolveError::new(Position, String)ResolveErrorConstruct from a position and message
msg()StringError message
pos()PositionSource position
SyntaxError::kind()SyntaxErrorKindStructural 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:

VariantMeaning
UnexpectedEofInput ended while a construct was still open (e.g. a compound opener or unclosed bracket) — may complete with more input
UnterminatedStringA string literal was not closed before end of input — may complete with more input
OtherAny other syntax error — genuinely invalid input

#Position

MethodReturnsDescription
Position::new(String, Int, Int)PositionConstruct from filename, line, column
filename()StringSource file name
line()Int1-based line number
col()Int1-based column (0 = unknown)
is_valid()Booltrue if line > 0
is_before(Position)BoolPositional comparison
to_string()String"<file>:<line>:<col>"

#Binding

A local variable name with its definition position; used by the debugger API.

MethodReturnsDescription
Binding::new(String, Position)BindingConstruct from a name and position
name()StringVariable name
pos()PositionDeclaration position in source

#CallStack and CallFrame

MethodReturnsDescription
CallStack::new(Array[CallFrame])CallStackConstruct from frames (0 = outermost)
length()IntNumber of frames
at(Int)CallFrame?Frame at index; None if out of range
pop()CallFrame?Remove and return the innermost frame
to_string()StringHuman-readable backtrace
CallFrame::new(String, Position)CallFrameConstruct from a name and call-site position
name()StringFunction name at this frame
pos()PositionCall-site position

#
Binding

source
pub struct Binding {
  // private fields
}

A local variable name together with its definition position; used by the debugger API.

#
Binding::name

source
fn Binding::name(self : Binding) -> String

Returns the variable name.

Returns the name string of this binding.

#
Binding::new

source
fn Binding::new(name : String, pos : Position) -> Binding

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.

#
Binding::pos

source
fn Binding::pos(self : Binding) -> Position

Returns the definition position of the variable.

Returns the Position where this variable is defined.

#
CallFrame

source
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

source
fn CallFrame::name(self : CallFrame) -> String

Returns the function name for this frame.

Returns the function name string.

#
CallFrame::new

source
fn CallFrame::new(name : String, pos : Position) -> CallFrame

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.

#
CallFrame::pos

source
fn CallFrame::pos(self : CallFrame) -> Position

Returns the source position recorded in this frame.

Returns the call-site Position for this frame.

#
CallStack

source
pub struct CallStack {
  // private fields
}

An ordered snapshot of call frames, outermost first, innermost last.

#
CallStack::at

source
fn CallStack::at(self : CallStack, i : Int) -> CallFrame?

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

source
fn CallStack::length(self : CallStack) -> Int

Returns the number of frames in the stack.

Returns the frame count as an Int.

#
CallStack::new

source
fn CallStack::new(frames : Array[CallFrame]) -> CallStack

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

source
fn CallStack::pop(self : CallStack) -> CallFrame?

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.

#
CallStack::to_string

source
fn CallStack::to_string(self : CallStack) -> String

Formats the stack as a Python-style traceback string, or "" if empty.

Returns the formatted traceback string.

#
EvalError

source
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

source
fn EvalError::backtrace(self : EvalError) -> String

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

source
fn EvalError::call_stack(self : EvalError) -> CallStack

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

source
fn EvalError::cause(self : EvalError) -> EvalError?

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

source
fn EvalError::msg(self : EvalError) -> String

Returns the error message string.

Returns the message string of this error.

#
EvalError::simple

source
fn EvalError::simple(msg : String) -> EvalError

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

source
fn EvalError::to_string(self : EvalError) -> String

Returns just the error message (same as msg); implements the Show trait.

Returns the error message string.

#
EvalError::with_cause

source
fn EvalError::with_cause(msg : String, call_stack : CallStack, cause : EvalError) -> EvalError

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

source
fn EvalError::with_stack(msg : String, call_stack : CallStack) -> EvalError

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

source
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

source
fn Position::col(self : Position) -> Int

Returns the 1-based column number, or 0 if the position is unknown.

Returns the column number as an Int.

#
Position::filename

source
fn Position::filename(self : Position) -> String

Returns the filename component of this position.

Returns the source file name string.

#
Position::is_before

source
fn Position::is_before(self : Position, other : Position) -> Bool

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

source
fn Position::is_valid(self : Position) -> Bool

Returns true if the position carries a meaningful line number.

Returns true when line > 0, false otherwise.

#
Position::line

source
fn Position::line(self : Position) -> Int

Returns the 1-based line number, or 0 if the position is unknown.

Returns the line number as an Int.

#
Position::new

source
fn Position::new(filename : String, line : Int, col : Int) -> Position

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.

#
Position::to_string

source
fn Position::to_string(self : Position) -> String

Formats the position as "file:line:col", "file:line", or "file", depending on which fields are non-zero.

Returns the formatted position string.

#
ResolveError

source
pub struct ResolveError {
  // private fields
}

A name-resolution error with a source position and a human-readable message.

#
ResolveError::msg

source
fn ResolveError::msg(self : ResolveError) -> String

Returns the human-readable error message.

Returns the error message string.

#
ResolveError::new

source
fn ResolveError::new(pos : Position, msg : String) -> ResolveError

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

source

Returns the source position where the resolve error was detected.

Returns the Position associated with this error.

#
ResolveError::to_string

source
fn ResolveError::to_string(self : ResolveError) -> String

Formats the error as "pos: msg".

Returns the formatted error string.

#
SyntaxError

source
pub struct SyntaxError {
  // private fields
}

A parse-time error with a source position and a human-readable message.

#
SyntaxError::kind

source

Returns the structural classification of the error.

Returns the SyntaxErrorKind associated with this error.

#
SyntaxError::msg

source
fn SyntaxError::msg(self : SyntaxError) -> String

Returns the human-readable error message.

Returns the error message string.

#
SyntaxError::new

source
fn SyntaxError::new(pos : Position, msg : String) -> SyntaxError

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

source
fn SyntaxError::pos(self : SyntaxError) -> Position

Returns the source position where the syntax error was detected.

Returns the Position associated with this error.

#
SyntaxError::to_string

source
fn SyntaxError::to_string(self : SyntaxError) -> String

Formats the error as "pos: msg".

Returns the formatted error string.

#
SyntaxError::with_kind

source
fn SyntaxError::with_kind(pos : Position, msg : String, kind : SyntaxErrorKind) -> SyntaxError

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

source
pub(all) enum SyntaxErrorKind {
  UnexpectedEof
  UnterminatedString
  Other
} derive(Eq)

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.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io