4.9 KiB
LuaJIT Go Wrapper API Documentation
State Management
NewSafe() *State
Creates a new Lua state with stack safety enabled.
L := luajit.NewSafe()
defer L.Close()
defer L.Cleanup()
New() *State
Creates a new Lua state without stack safety checks.
L := luajit.New()
defer L.Close()
defer L.Cleanup()
Close()
Closes the Lua state and frees associated resources.
L.Close()
Cleanup()
Cleans up the function registry and other internal resources.
L.Cleanup()
Stack Operations
GetTop() int
Returns the index of the top element in the stack.
top := L.GetTop() // 0 for empty stack
Pop(n int)
Removes n elements from the stack.
L.Pop(1) // Remove top element
L.Pop(2) // Remove top two elements
Remove(index int)
Removes the element at the given index.
L.Remove(-1) // Remove top element
L.Remove(1) // Remove first element
checkStack(n int) error
Internal function that ensures there's enough space for n new elements.
if err := L.checkStack(2); err != nil {
return err
}
Type Checks
GetType(index int) LuaType
Returns the type of the value at the given index.
if L.GetType(-1) == TypeString {
// Handle string
}
IsFunction(index int) bool
IsTable(index int) bool
IsUserData(index int) bool
Type checking functions for specific Lua types.
if L.IsTable(-1) {
table, err := L.ToTable(-1)
}
Value Retrieval
ToString(index int) string
Converts the value at the given index to a string.
str := L.ToString(-1)
ToNumber(index int) float64
Converts the value to a number.
num := L.ToNumber(-1)
ToBoolean(index int) bool
Converts the value to a boolean.
bool := L.ToBoolean(-1)
ToValue(index int) (interface{}, error)
Converts any Lua value to its Go equivalent.
val, err := L.ToValue(-1)
if err != nil {
return err
}
ToTable(index int) (map[string]interface{}, error)
Converts a Lua table to a Go map.
table, err := L.ToTable(-1)
if err != nil {
return nil, err
}
Value Pushing
PushNil()
PushBoolean(b bool)
PushNumber(n float64)
PushString(str string)
Basic value pushing functions.
L.PushString("hello")
L.PushNumber(42)
L.PushBoolean(true)
L.PushNil()
PushValue(v interface{}) error
Pushes any Go value onto the stack.
err := L.PushValue(myValue)
PushTable(table map[string]interface{}) error
Pushes a Go map as a Lua table.
data := map[string]interface{}{
"key": "value",
"numbers": []float64{1, 2, 3},
}
err := L.PushTable(data)
Function Registration
RegisterGoFunction(name string, fn GoFunction) error
Registers a Go function that can be called from Lua.
adder := func(s *State) int {
sum := s.ToNumber(1) + s.ToNumber(2)
s.PushNumber(sum)
return 1
}
err := L.RegisterGoFunction("add", adder)
UnregisterGoFunction(name string)
Removes a previously registered function.
L.UnregisterGoFunction("add")
Package Management
SetPackagePath(path string) error
Sets the Lua package.path variable.
err := L.SetPackagePath("./?.lua;/usr/local/share/lua/5.1/?.lua")
AddPackagePath(path string) error
Adds a path to the existing package.path.
err := L.AddPackagePath("./modules/?.lua")
Code Execution
DoString(str string) error
Executes a string of Lua code.
err := L.DoString(`
local x = 40
local y = 2
result = x + y
`)
DoFile(filename string) error
Executes a Lua file.
err := L.DoFile("script.lua")
Table Operations
GetField(index int, key string)
Gets a field from a table at the given index.
L.GetField(-1, "name") // gets table.name
SetField(index int, key string)
Sets a field in a table at the given index.
L.PushString("value")
L.SetField(-2, "key") // table.key = "value"
GetGlobal(name string)
Gets a global variable.
L.GetGlobal("myGlobal")
SetGlobal(name string)
Sets a global variable from the value at the top of the stack.
L.PushNumber(42)
L.SetGlobal("answer") // answer = 42
Error Handling
LuaError
Error type containing both an error code and message.
type LuaError struct {
Code int
Message string
}
getStackTrace() string
Gets the current Lua stack trace.
trace := L.getStackTrace()
fmt.Println(trace)
Thread Safety Notes
- The function registry is thread-safe
- Individual Lua states are not thread-safe
- Create separate states for concurrent operations
- Use the function registry to share functions between states
Memory Management
Always pair state creation with cleanup:
L := luajit.NewSafe()
defer L.Close()
defer L.Cleanup()
Stack management in unsafe mode requires manual attention:
L := luajit.New()
L.PushString("hello")
// ... use the string
L.Pop(1) // Clean up when done