Lua.AST.Meta (Lua v1.0.0-rc.2)

Position tracking metadata for AST nodes.

Every AST node includes a meta field containing position information for error reporting, source maps, and debugging.

Comments can be attached to AST nodes via the metadata field:

:leading_comments - Comments before the node
:trailing_comment - Inline comment after the node on the same line

Summary

Types

comment()

position()

t()

Functions

add_leading_comment(meta, comment)

Adds a leading comment to a Meta struct.

add_metadata(meta, key, value)

Adds metadata to an existing Meta struct.

get_leading_comments(arg1)

Gets leading comments from a Meta struct.

get_trailing_comment(arg1)

Gets trailing comment from a Meta struct.

merge(meta1, meta2)

Merges two Meta structs, taking the earliest start and latest end.

new(start \\ nil, end_pos \\ nil, metadata \\ %{})

Creates a new Meta struct with start and end positions.

set_trailing_comment(meta, comment)

Sets the trailing comment for a Meta struct.

Types

comment()

@type comment() :: %{type: :single | :multi, text: String.t(), position: position()}

position()

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

t()

@type t() :: %Lua.AST.Meta{
  end: position() | nil,
  metadata: map(),
  start: position() | nil
}

Functions

add_leading_comment(meta, comment)

@spec add_leading_comment(t(), comment()) :: t()

Adds a leading comment to a Meta struct.

Leading comments appear before the AST node.

add_metadata(meta, key, value)

@spec add_metadata(t(), atom(), term()) :: t()

Adds metadata to an existing Meta struct.

get_leading_comments(arg1)

@spec get_leading_comments(t() | nil) :: [comment()]

Gets leading comments from a Meta struct.

get_trailing_comment(arg1)

@spec get_trailing_comment(t() | nil) :: comment() | nil

Gets trailing comment from a Meta struct.

merge(meta1, meta2)

@spec merge(t(), t()) :: t()

Merges two Meta structs, taking the earliest start and latest end.

Useful when combining multiple nodes into a single parent node.

Examples

iex> meta1 = Lua.AST.Meta.new(%{line: 1, column: 1, byte_offset: 0}, %{line: 1, column: 5, byte_offset: 4})
iex> meta2 = Lua.AST.Meta.new(%{line: 1, column: 7, byte_offset: 6}, %{line: 1, column: 10, byte_offset: 9})
iex> Lua.AST.Meta.merge(meta1, meta2)
%Lua.AST.Meta{
  start: %{line: 1, column: 1, byte_offset: 0},
  end: %{line: 1, column: 10, byte_offset: 9},
  metadata: %{}
}

new(start \\ nil, end_pos \\ nil, metadata \\ %{})

@spec new(position() | nil, position() | nil, map()) :: t()

Creates a new Meta struct with start and end positions.

Examples

iex> Lua.AST.Meta.new(
...>   %{line: 1, column: 1, byte_offset: 0},
...>   %{line: 1, column: 5, byte_offset: 4}
...> )
%Lua.AST.Meta{
  start: %{line: 1, column: 1, byte_offset: 0},
  end: %{line: 1, column: 5, byte_offset: 4},
  metadata: %{}
}

set_trailing_comment(meta, comment)

@spec set_trailing_comment(t(), comment()) :: t()

Sets the trailing comment for a Meta struct.

A trailing comment appears on the same line as the AST node. Only one trailing comment is allowed per node.