obitools4/autodoc/docmd/pkg/obilua/lua_push_interface.md

Semantic Description of obilua Package

The obilua package provides utilities for bi-directional data marshaling between Go and Lua, specifically focusing on converting native Go values into equivalent lua.LValue types for use in a Lua state (*lua.LState). This enables Go applications to expose structured data (e.g., maps, slices) or synchronization primitives (*sync.Mutex) directly to Lua scripts.

Core Functionality

• pushInterfaceToLua(L, val):
  Main dispatcher that inspects the type of a Go interface{} value and routes it to specialized conversion functions. Supported types include:

  • Basic scalar types: string, bool, int, float64
  • Collections:
    • Maps: map[string]{string,int,bool,float64,interface{}}
    • Slices/arrays: []{string,int,byte,float64,bool]interface{}}
  • Special cases:
    • nil → Lua’s LNil
    • *sync.Mutex (via dedicated handler)

• Type-Specific Pushers:
  Each helper function (pushMapStringIntToLua, pushSliceBoolToLua, etc.) constructs a new Lua table and populates it with converted elements using appropriate lua.LValue constructors (LString, LNumber, LBool).

  • Maps are converted as associative tables (keyed by string).
  • Slices become indexed Lua arrays (1..n).

• Generic Slice Support:
  pushSliceNumericToLua[T]() uses Go generics to handle numeric slices (int, float64, byte) uniformly.

Design Notes

• No reverse conversion (Lua → Go) is included — only pushing to Lua.
• Strict typing: Unsupported types trigger a fatal log (log.Fatalf), enforcing explicit type handling.
• Lua semantics respected: Tables are 1-indexed, and numeric types map to lua.LNumber.

This package is ideal for embedding Lua in Go services where dynamic configuration, rule evaluation, or scripting requires safe and predictable data injection.