Lua.VM.Display (Lua v1.0.0-rc.1)

Boundary wrappers that turn opaque VM value tags into display structs at the Lua.eval!/2 return path.

The internal VM continues to use the tagged-tuple representation ({:tref, id}, {:lua_closure, proto, upvalues}, {:native_func, fun}, {:udref, id}). These wrappers exist purely so that values that surface to user code in iex render legibly instead of as opaque tuples.

See Lua.VM.Display.Table, Lua.VM.Display.Closure, Lua.VM.Display.NativeFunc, and Lua.VM.Display.Userdata for the per-tag display structs and their Inspect impls.

Decode behaviour

Tag	`decode: true`	`decode: false`
`{:tref, _}`	list of `{k, v}` (unchanged)	wraps to `Display.Table`
`{:udref, _}`	`{:userdata, term}` (unchanged)	wraps to `Display.Userdata`
`{:lua_closure, _, _}`	wraps to `Display.Closure`	wraps to `Display.Closure`
`{:native_func, _}`	wraps to `Display.NativeFunc`	wraps to `Display.NativeFunc`

Default-decode tables and userdata are left in their existing Elixir-friendly shape so deflua flows and downstream consumers do not need to change.

Summary

Types

display_struct()

Any of the four display structs produced at the eval boundary.

Functions

display_struct?(arg1)

Returns true when the value is one of the four display structs.

unwrap(other)

Unwraps a display struct back to its underlying VM tag tuple.

wrap_results(values, state, decode?)

Wraps each value in a list of eval results for display, given the state at boundary-cross time and the decode: option.

wrap_value(value, state, decode?)

Wraps a single eval-result value for display.

Types

display_struct()

@type display_struct() ::
  Lua.VM.Display.Table.t()
  | Lua.VM.Display.Closure.t()
  | Lua.VM.Display.NativeFunc.t()
  | Lua.VM.Display.Userdata.t()

Any of the four display structs produced at the eval boundary.

Functions

display_struct?(arg1)

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

Returns true when the value is one of the four display structs.

Used by API entry points (Lua.set!/3, Lua.encode!/2, etc.) to detect a wrapped-for-display value that should be unwrapped back to its underlying VM tag before further processing.

unwrap(other)

@spec unwrap(term()) :: term()

Unwraps a display struct back to its underlying VM tag tuple.

Returns the value unchanged if it is not a display struct.

wrap_results(values, state, decode?)

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

Wraps each value in a list of eval results for display, given the state at boundary-cross time and the decode: option.

When decode: true (the default), tables and userdata are passed through unchanged because they have already been decoded into Elixir-friendly shapes (list of tuples and {:userdata, term}). Closures and native funcs are wrapped in either mode.

When decode: false, all four tag kinds are wrapped; nested values inside tables are also wrapped via wrap_value/2.

wrap_value(value, state, decode?)

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

Wraps a single eval-result value for display.

See wrap_results/3 for the decode-mode matrix.