LuaJIT-to-Go/DOCS.md

# LuaJIT Go Wrapper API Documentation

## State Management

### NewSafe() *State
Creates a new Lua state with stack safety enabled.
```go
L := luajit.NewSafe()
defer L.Close()
defer L.Cleanup()
```

### New() *State
Creates a new Lua state without stack safety checks.
```go
L := luajit.New()
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
```

### 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
```

### checkStack(n int) error
Internal function that ensures there's enough space for n new elements.
```go
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.
```go
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.
```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) (interface{}, error)
Converts any Lua value to its Go equivalent.
```go
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.
```go
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.
```go
L.PushString("hello")
L.PushNumber(42)
L.PushBoolean(true)
L.PushNil()
```

### PushValue(v interface{}) error
Pushes any Go value onto the stack.
```go
err := L.PushValue(myValue)
```

### PushTable(table map[string]interface{}) error
Pushes a Go map as a Lua table.
```go
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.
```go
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.
```go
L.UnregisterGoFunction("add")
```

## Package Management

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

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

## Code Execution

### DoString(str 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")
```

## Table Operations

### GetField(index int, key string)
Gets a field from a table at the given index.
```go
L.GetField(-1, "name")  // gets table.name
```

### SetField(index int, key string)
Sets a field in a table at the given index.
```go
L.PushString("value")
L.SetField(-2, "key")  // table.key = "value"
```

### GetGlobal(name string)
Gets a global variable.
```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
```

## Error Handling

### LuaError
Error type containing both an error code and message.
```go
type LuaError struct {
    Code    int
    Message string
}
```

### getStackTrace() string
Gets the current Lua stack trace.
```go
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:
```go
L := luajit.NewSafe()
defer L.Close()
defer L.Cleanup()
```

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