Lua.Parser.Error (Lua v1.0.1)

View Source

Structured, wire-safe error reporting for the Lua parser.

Each error carries:

  • Source code context with line numbers
  • Position information pointing to the error location
  • A human-readable message and, where possible, a suggested fix
  • Related errors, for multi-error reporting

Produced when parsing fails: the parser's parse_structured/1 entry point returns {:error, [t()]}. Call to_map/2 for a JSON-serializable shape suitable for editors, LSPs, and web frontends.

Summary

Types

error_type()
position()
source_context()
t()
wire_error()

Wire-safe representation produced by to_map/2. Mirrors the shape used for runtime errors so runtime and parse errors render through one path. source, call_stack, and error_kind are constant for parse errors (no file name, stack, or error kind) and exist only for shape parity.

Functions

expected_token(expected_type, expected_value, got_type, got_value, position)

Creates an error for expected token.

format(error, source_code)

Formats an error into a beautiful multi-line string with context.

format_multiple(errors, source_code)

Formats multiple errors together.

new(type, message, position \\ nil, opts \\ [])

Creates a new error.

to_map(error, source_code \\ nil)

Returns a wire-safe structured representation of a parse error.

unclosed_delimiter(delimiter, open_pos, close_pos \\ nil)

Creates an error for unclosed delimiter.

unexpected_end(context, position \\ nil)

Creates an error for unexpected end of input.

unexpected_token(token_type, token_value, position, context)

Creates an error for unexpected token.

Types

error_type()

@type error_type() ::
  :unexpected_token
  | :unexpected_end
  | :expected_token
  | :unclosed_delimiter
  | :invalid_syntax
  | :lexer_error
  | :multiple_errors

position()

@type position() :: %{
  line: pos_integer(),
  column: pos_integer(),
  byte_offset: non_neg_integer()
}

source_context()

@type source_context() :: %{
  lines: [%{number: pos_integer(), text: String.t(), highlight?: boolean()}],
  pointer_column: pos_integer()
}

t()

@type t() :: %Lua.Parser.Error{
  message: String.t(),
  position: position() | nil,
  related: [t()],
  source_lines: [String.t()],
  suggestion: String.t() | nil,
  type: error_type()
}

wire_error()

@type wire_error() :: %{
  type: error_type(),
  message: String.t() | nil,
  source: nil,
  line: pos_integer() | nil,
  call_stack: [],
  source_context: source_context() | nil,
  suggestion: String.t() | nil,
  error_kind: nil
}

Wire-safe representation produced by to_map/2. Mirrors the shape used for runtime errors so runtime and parse errors render through one path. source, call_stack, and error_kind are constant for parse errors (no file name, stack, or error kind) and exist only for shape parity.

Functions

expected_token(expected_type, expected_value, got_type, got_value, position)

@spec expected_token(atom(), term() | nil, atom(), term(), position()) :: t()

Creates an error for expected token.

format(error, source_code)

@spec format(t(), String.t()) :: String.t()

Formats an error into a beautiful multi-line string with context.

format_multiple(errors, source_code)

@spec format_multiple([t()], String.t()) :: String.t()

Formats multiple errors together.

new(type, message, position \\ nil, opts \\ [])

@spec new(error_type(), String.t(), position() | nil, keyword()) :: t()

Creates a new error.

to_map(error, source_code \\ nil)

@spec to_map(t(), String.t() | nil) :: wire_error()

Returns a wire-safe structured representation of a parse error.

The shape is identical to the map produced for runtime errors, so runtime and parse errors can flow through a single renderer (HTML, JSON, structured logs). No ANSI escapes appear in any string field, and leading/trailing whitespace from the internal message/suggestion templates is trimmed. Every string field is valid UTF-8 and safe to Jason.encode!/1 — even when the offending source token is a non-ASCII or malformed byte.

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

Parse errors carry no call stack or error kind, so call_stack is always [] and error_kind is always nil; they are present for shape parity. source is nil because the parser does not track a file name.

Pass the original source code as the second argument to populate source_context. The pointer_column is taken from the error's real column when a position is known, so the ^ marker lands on the offending token instead of always pointing at column 1.

iex> {:error, [error]} = Lua.Parser.parse_structured("if x then")
iex> map = Lua.Parser.Error.to_map(error, "if x then")
iex> {map.type, map.source_context.pointer_column}
{:unexpected_token, 10}

unclosed_delimiter(delimiter, open_pos, close_pos \\ nil)

@spec unclosed_delimiter(atom(), position(), position() | nil) :: t()

Creates an error for unclosed delimiter.

unexpected_end(context, position \\ nil)

@spec unexpected_end(String.t(), position() | nil) :: t()

Creates an error for unexpected end of input.

unexpected_token(token_type, token_value, position, context)

@spec unexpected_token(atom(), term(), position(), String.t()) :: t()

Creates an error for unexpected token.