LuaJIT-to-Go/DOCS.md

# API Documentation

## State Management

### New() *State
New creates a new Lua state with optional standard libraries; true if not specified
```go
L := luajit.New() // or luajit.New(false)
defer L.Close()
defer L.Cleanup()
```

### Close()
Closes the Lua state and frees associated resources.
```go
L.Close()
```

### Cleanup()
Cleans up the function registry and other internal resources.
```go
L.Cleanup()
```

## Stack Operations

### GetTop() int
Returns the index of the top element in the stack.
```go
top := L.GetTop()  // 0 for empty stack
```

### SetTop(index int)
Sets the stack top to a specific index.
```go
L.SetTop(2)  // Truncate stack to 2 elements
```

### PushCopy(index int)
Pushes a copy of the value at the given index onto the stack.
```go
L.PushCopy(-1)  // Duplicate the top element
```

### Pop(n int)
Removes n elements from the stack.
```go
L.Pop(1)  // Remove top element
L.Pop(2)  // Remove top two elements
```

### Remove(index int)
Removes the element at the given index.
```go
L.Remove(-1)  // Remove top element
L.Remove(1)   // Remove first element
```

## Type Checks

### GetType(index int) LuaType
Returns the type of the value at the given index.
```go
if L.GetType(-1) == TypeString {
    // Handle string
}
```

### IsNil(index int) bool
### IsBoolean(index int) bool
### IsNumber(index int) bool
### IsString(index int) bool
### IsTable(index int) bool
### IsFunction(index int) bool
Type checking functions for specific Lua types.
```go
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.
```go
str := L.ToString(-1)
```

### ToNumber(index int) float64
Converts the value to a number.
```go
num := L.ToNumber(-1)
```

### ToBoolean(index int) bool
Converts the value to a boolean.
```go
bool := L.ToBoolean(-1)
```

### ToValue(index int) (any, error)
Converts any Lua value to its Go equivalent with automatic type detection.
```go
val, err := L.ToValue(-1)
if err != nil {
    return err
}
```

### ToTable(index int) (any, error)
Converts a Lua table to optimal Go type; arrays or `map[string]any`.
```go
table, err := L.ToTable(-1)
if err != nil {
    return nil, err
}
```

### GetTableLength(index int) int
Returns the length of a table at the given index.
```go
length := L.GetTableLength(-1)
```

## Value Pushing

### PushNil()
### PushBoolean(b bool)
### PushNumber(n float64)
### PushString(str string)
Basic value pushing functions.
```go
L.PushString("hello")
L.PushNumber(42)
L.PushBoolean(true)
L.PushNil()
```

### PushValue(v any) error
Pushes any Go value onto the stack with comprehensive type support.
```go
// Supports: primitives, slices, maps with various type combinations
err := L.PushValue(map[string]any{
    "key": "value",
    "numbers": []float64{1, 2, 3},
})
```

## Table Operations

### CreateTable(narr, nrec int)
Creates a new table with pre-allocated space.
```go
L.CreateTable(10, 5)  // Space for 10 array elements, 5 records
```

### NewTable()
Creates a new empty table and pushes it onto the stack.
```go
L.NewTable()
```

### GetTable(index int)
Gets a table field (t[k]) where t is at the given index and k is at the top of the stack.
```go
L.PushString("key")
L.GetTable(-2)  // Gets table["key"]
```

### SetTable(index int)
Sets a table field (t[k] = v) where t is at the given index, k is at -2, and v is at -1.
```go
L.PushString("key")
L.PushString("value")
L.SetTable(-3)  // table["key"] = "value"
```

### GetField(index int, key string)
Gets a table field t[k] and pushes it onto the stack.
```go
L.GetField(-1, "name")  // gets table.name
```

### SetField(index int, key string)
Sets a table field t[k] = v, where v is the value at the top of the stack.
```go
L.PushString("value")
L.SetField(-2, "key")  // table.key = "value"
```

### Next(index int) bool
Pops a key from the stack and pushes the next key-value pair from the table.
```go
L.PushNil()  // Start iteration
for L.Next(-2) {
    // Stack now has key at -2 and value at -1
    key := L.ToString(-2)
    value := L.ToString(-1)
    L.Pop(1)  // Remove value, keep key for next iteration
}
```

### GetFieldString/Number/Bool/Table(index int, key string, default T) T
Get typed fields from tables with default values.
```go
name := L.GetFieldString(-1, "name", "unknown")
age := L.GetFieldNumber(-1, "age", 0)
active := L.GetFieldBool(-1, "active", false)
config, ok := L.GetFieldTable(-1, "config")
```

### ForEachTableKV(index int, fn func(key, value string) bool)
### ForEachArray(index int, fn func(i int, state *State) bool)
Convenient iteration helpers.
```go
L.ForEachTableKV(-1, func(key, value string) bool {
    fmt.Printf("%s: %s\n", key, value)
    return true  // continue iteration
})
```

## Function Registration and Calling

### GoFunction
Type definition for Go functions callable from Lua.
```go
type GoFunction func(*State) int
```

### PushGoFunction(fn GoFunction) error
Wraps a Go function and pushes it onto the Lua stack.
```go
adder := func(s *luajit.State) int {
    sum := s.ToNumber(1) + s.ToNumber(2)
    s.PushNumber(sum)
    return 1
}
err := L.PushGoFunction(adder)
```

### RegisterGoFunction(name string, fn GoFunction) error
Registers a Go function as a global Lua function.
```go
err := L.RegisterGoFunction("add", adder)
```

### UnregisterGoFunction(name string)
Removes a previously registered function.
```go
L.UnregisterGoFunction("add")
```

### Call(nargs, nresults int) error
Calls a function with the given number of arguments and results.
```go
L.GetGlobal("myfunction")
L.PushNumber(1)
L.PushNumber(2)
err := L.Call(2, 1)  // Call with 2 args, expect 1 result
```

### CallGlobal(name string, args ...any) ([]any, error)
Calls a global function with arguments and returns all results.
```go
results, err := L.CallGlobal("myfunction", 1, 2, "hello")
```

## Global Operations

### GetGlobal(name string)
Gets a global variable and pushes it onto the stack.
```go
L.GetGlobal("myGlobal")
```

### SetGlobal(name string)
Sets a global variable from the value at the top of the stack.
```go
L.PushNumber(42)
L.SetGlobal("answer")  // answer = 42
```

## Code Execution

### LoadString(code string) error
Loads a Lua chunk from a string without executing it.
```go
err := L.LoadString("return 42")
```

### LoadFile(filename string) error
Loads a Lua chunk from a file without executing it.
```go
err := L.LoadFile("script.lua")
```

### DoString(code string) error
Executes a string of Lua code.
```go
err := L.DoString(`
    local x = 40
    local y = 2
    result = x + y
`)
```

### DoFile(filename string) error
Executes a Lua file.
```go
err := L.DoFile("script.lua")
```

### Execute(code string) (int, error)
Executes a Lua string and returns the number of results left on the stack.
```go
nresults, err := L.Execute("return 1, 2, 3")
// nresults would be 3
```

### ExecuteWithResult(code string) (any, error)
Executes a Lua string and returns the first result.
```go
result, err := L.ExecuteWithResult("return 'hello'")
// result would be "hello"
```

### BatchExecute(statements []string) error
Executes multiple statements as a single batch.
```go
err := L.BatchExecute([]string{
    "x = 10",
    "y = 20",
    "result = x + y",
})
```

## Bytecode Operations

### CompileBytecode(code string, name string) ([]byte, error)
Compiles a Lua chunk to bytecode without executing it.
```go
bytecode, err := L.CompileBytecode("return 42", "test")
```

### LoadBytecode(bytecode []byte, name string) error
Loads precompiled bytecode without executing it.
```go
err := L.LoadBytecode(bytecode, "test")
```

### RunBytecode() error
Executes previously loaded bytecode with 0 results.
```go
err := L.RunBytecode()
```

### RunBytecodeWithResults(nresults int) error
Executes bytecode and keeps nresults on the stack.
```go
err := L.RunBytecodeWithResults(1)
```

### LoadAndRunBytecode(bytecode []byte, name string) error
Loads and executes bytecode.
```go
err := L.LoadAndRunBytecode(bytecode, "test")
```

### LoadAndRunBytecodeWithResults(bytecode []byte, name string, nresults int) error
Loads and executes bytecode, preserving results.
```go
err := L.LoadAndRunBytecodeWithResults(bytecode, "test", 1)
```

### CompileAndRun(code string, name string) error
Compiles and immediately executes Lua code.
```go
err := L.CompileAndRun("answer = 42", "test")
```

## Package Path Operations

### SetPackagePath(path string) error
Sets the Lua package.path.
```go
err := L.SetPackagePath("./?.lua;/usr/local/share/lua/5.1/?.lua")
```

### AddPackagePath(path string) error
Adds a path to package.path.
```go
err := L.AddPackagePath("./modules/?.lua")
```

## Metatable Operations

### SetMetatable(index int)
Sets the metatable for the value at the given index.
```go
L.SetMetatable(-1)
```

### GetMetatable(index int) bool
Gets the metatable for the value at the given index.
```go
if L.GetMetatable(-1) {
    // Metatable is now on stack
    L.Pop(1)
}
```

## Error Handling

### LuaError
Enhanced error type with detailed context information.
```go
type LuaError struct {
    Code       int
    Message    string
    File       string
    Line       int
    StackTrace string
    Context    string
}
```

### GetStackTrace() string
Gets the current Lua stack trace.
```go
trace := L.GetStackTrace()
fmt.Println(trace)
```

### GetErrorInfo(context string) *LuaError
Extracts detailed error information from the Lua stack.
```go
err := L.GetErrorInfo("MyFunction")
```

### CreateLuaError(code int, context string) *LuaError
Creates a LuaError with full context information.
```go
err := L.CreateLuaError(status, "DoString")
```

### PushError(format string, args ...any) int
Pushes an error string and returns -1.
```go
return s.PushError("invalid argument: %v", arg)
```

## Validation

### CheckArgs(specs ...ArgSpec) error
Validates function arguments against specifications.
```go
err := s.CheckArgs(
    ArgSpec{Name: "name", Type: "string", Required: true, Check: CheckString},
    ArgSpec{Name: "age", Type: "number", Required: false, Check: CheckNumber},
)
```

### CheckMinArgs/CheckExactArgs(n int) error
Argument count validation.
```go
if err := s.CheckMinArgs(2); err != nil {
    return s.PushError(err.Error())
}
```

### SafeToString/Number/Table(index int) (T, error)
Safe value conversion with error handling.
```go
str, err := s.SafeToString(1)
if err != nil {
    return s.PushError(err.Error())
}
```

## Table Building

### NewTableBuilder() *TableBuilder
Creates a new table builder for fluent table construction.
```go
L.NewTableBuilder().
    SetString("name", "John").
    SetNumber("age", 30).
    SetBool("active", true).
    Build()
```

## 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:
```go
L := luajit.New()
defer L.Close()
defer L.Cleanup()
```

Stack management requires manual attention:
```go
L.PushString("hello")
// ... use the string
L.Pop(1)  // Clean up when done
```