@spec decode(term(), Lua.VM.State.t()) :: term()

Decodes a Lua VM value into an Elixir-friendly representation.

Tables are returned as lists of {key, decoded_value} tuples. Functions (closures, native) pass through as-is.

@spec decode_list([term()], Lua.VM.State.t()) :: [term()]

Decodes a list of Lua VM values.

@spec encode(term(), Lua.VM.State.t()) :: {term(), Lua.VM.State.t()}

Encodes an Elixir value into the Lua VM's internal representation.

Returns {encoded_value, state} since encoding maps and lists allocates tables.

@spec encode_list([term()], Lua.VM.State.t()) :: {[term()], Lua.VM.State.t()}

Encodes a list of Elixir values, threading state through each encoding.

Returns {encoded_values, state}.

@spec parse_number(String.t()) :: number() | nil

Parses a string to a number (integer or float), supporting hex notation.

Hex integer literals overflow-wrap into the signed 64-bit range per Lua 5.3 §3.1 (e.g. "0xFFFFFFFFFFFFFFFF" → -1). Hex floats with a fractional part or binary exponent (e.g. "0xAA.0", "0x1.8p3") are also supported.

Returns nil if the string cannot be parsed.

@spec sequence_length(map()) :: non_neg_integer()

Computes the Lua sequence length of a table's data map.

Finds the largest N where keys 1..N are all present.

@spec to_string(term()) :: String.t()

Converts a Lua value to its string representation.

@spec truthy?(term()) :: boolean()

Returns whether a Lua value is truthy.

In Lua, only nil and false are falsy. Everything else is truthy.

@spec type_name(term()) :: String.t()

Returns the Lua type name as a string for the given value.