Lua.VM.ErrorFormatter (Lua v1.0.0-rc.2)

View Source

Error formatting for Lua runtime errors.

Two entry points share the same underlying data:

  • format/3 renders a multi-line string for terminal output (location, message body, source context with pointer, stack trace, suggestion). ANSI color is applied only when IO.ANSI.enabled?/0 is true, so the same render path is safe whether the output goes to a TTY or is piped to a file.
  • to_map/3 returns a wire-safe structured map for non-terminal consumers (HTML rendering, JSON payloads, structured logs). No ANSI escapes appear in any string field.

The rendered layout leads with the source location so the reader sees where before what:

at demo.lua:3:

  attempt to perform arithmetic on a nil value
  ...

There is deliberately no separate "Runtime Type Error" header line — the public Lua.RuntimeException already prefixes Lua runtime error:, and the message body itself ("attempt to ...", "assertion failed: ...") names the category. Stacking a second header would be redundant.

Summary

Functions

format(error_type, message, opts \\ [])

Formats a runtime error into a multi-line string.

to_map(error_type, message, opts \\ [])

Returns a wire-safe structured representation of an error.

Functions

format(error_type, message, opts \\ [])

Formats a runtime error into a multi-line string.

ANSI color is applied only when IO.ANSI.enabled?/0 returns true.

Options

  • :source - Source file name
  • :line - Line number where error occurred
  • :call_stack - List of stack frames
  • :source_code - Full source code for context display
  • :error_kind - Structured error kind atom for suggestions (e.g., :call_nil, :call_non_function, :index_non_table)
  • :value_type - Type of the problematic value (e.g., :number, :string, :table)

to_map(error_type, message, opts \\ [])

Returns a wire-safe structured representation of an error.

The shape:

%{
  type: atom(),
  message: String.t(),
  source: String.t() | nil,
  line: pos_integer() | nil,
  call_stack: [%{source: String.t() | nil, line: pos_integer() | nil, name: String.t() | nil}],
  source_context: %{
    lines: [%{number: pos_integer(), text: String.t(), highlight?: boolean()}],
    pointer_column: pos_integer() | nil
  } | nil,
  suggestion: String.t() | nil,
  error_kind: atom() | nil
}

source_context is only populated when both :source_code and :line are provided. pointer_column reflects the column where the ^ marker points; the formatter does not currently track real column positions, so it is 1 when a highlighted line is present and nil otherwise.

Options

Accepts the same options as format/3.