update documentation

API.md

@@ -0,0 +1,82 @@
+# API Quick Reference
+
+## Core State
+- New(openLibs ...bool) *State
+- Close()
+- Cleanup()
+
+## Stack
+- GetTop() int
+- SetTop(index int)
+- Pop(n int)
+- PushCopy(index int)
+- Remove(index int)
+
+## Type Checks
+- GetType(index int) LuaType
+- IsNil/IsBoolean/IsNumber/IsString/IsTable/IsFunction(index int) bool
+
+## Values
+- ToString/ToNumber/ToBoolean(index int) T
+- ToValue(index int) (any, error)
+- ToTable(index int) (any, error)
+- PushNil/PushBoolean/PushNumber/PushString/PushValue()
+
+## Tables
+- NewTable()
+- CreateTable(narr, nrec int)
+- GetTable/SetTable(index int)
+- GetField/SetField(index int, key string)
+- GetFieldString/Number/Bool/Table(index int, key string, default T) T
+- GetTableLength(index int) int
+- Next(index int) bool
+- ForEachTableKV/ForEachArray(index int, fn func)
+- NewTableBuilder() *TableBuilder
+
+## Functions
+- RegisterGoFunction(name string, fn GoFunction) error
+- UnregisterGoFunction(name string)
+- PushGoFunction(fn GoFunction) error
+- Call(nargs, nresults int) error
+- CallGlobal(name string, args ...any) ([]any, error)
+
+## Globals
+- GetGlobal/SetGlobal(name string)
+
+## Execution
+- LoadString/LoadFile(source string) error
+- DoString/DoFile(source string) error
+- Execute(code string) (int, error)
+- ExecuteWithResult(code string) (any, error)
+- BatchExecute(statements []string) error
+
+## Bytecode
+- CompileBytecode(code, name string) ([]byte, error)
+- LoadBytecode(bytecode []byte, name string) error
+- RunBytecode() error
+- RunBytecodeWithResults(nresults int) error
+- LoadAndRunBytecode(bytecode []byte, name string) error
+- LoadAndRunBytecodeWithResults(bytecode []byte, name string, nresults int) error
+- CompileAndRun(code, name string) error
+
+## Validation
+- CheckArgs(specs ...ArgSpec) error
+- CheckMinArgs/CheckExactArgs(n int) error
+- SafeToString/Number/Table(index int) (T, error)
+
+## Error Handling
+- PushError(format string, args ...any) int
+- GetStackTrace() string
+- GetErrorInfo(context string) *LuaError
+- CreateLuaError(code int, context string) *LuaError
+
+## Package
+- SetPackagePath/AddPackagePath(path string) error
+
+## Metatable
+- SetMetatable(index int)
+- GetMetatable(index int) bool
+
+## Constants
+- TypeNil/Boolean/Number/String/Table/Function/UserData/Thread
+- LUA_MINSTACK/MAXSTACK/REGISTRYINDEX/GLOBALSINDEX

DOCS.md

@@ -56,17 +56,6 @@ L.Remove(-1)  // Remove top element
 L.Remove(1)   // Remove first element
 ```
 
-### absIndex(index int) int
-Internal function that converts a possibly negative index to its absolute position.
-
-### 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
@@ -111,7 +100,7 @@ bool := L.ToBoolean(-1)
 ```
 
 ### ToValue(index int) (any, error)
-Converts any Lua value to its Go equivalent.
+Converts any Lua value to its Go equivalent with automatic type detection.
 ```go
 val, err := L.ToValue(-1)
 if err != nil {
@@ -119,8 +108,8 @@ if err != nil {
 }
 ```
 
-### ToTable(index int) (map[string]any, error)
+### ToTable(index int) (any, error)
-Converts a Lua table to a Go map.
+Converts a Lua table to optimal Go type ([]int, []string, map[string]any, etc.).
 ```go
 table, err := L.ToTable(-1)
 if err != nil {
@@ -149,19 +138,13 @@ L.PushNil()
 ```
 
 ### PushValue(v any) error
-Pushes any Go value onto the stack.
+Pushes any Go value onto the stack with comprehensive type support.
 ```go
-err := L.PushValue(myValue)
+// Supports: primitives, slices, maps with various type combinations
-```
+err := L.PushValue(map[string]any{
-
-### PushTable(table map[string]any) error
-Pushes a Go map as a Lua table.
-```go
-data := map[string]any{
     "key": "value",
     "numbers": []float64{1, 2, 3},
-}
+})
-err := L.PushTable(data)
 ```
 
 ## Table Operations
@@ -218,6 +201,25 @@ for L.Next(-2) {
 }
 ```
 
+### 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
@@ -258,6 +260,12 @@ 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)
@@ -317,6 +325,16 @@ 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)
@@ -375,14 +393,35 @@ Adds a path to package.path.
 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
-Error type containing both an error code and message.
+Enhanced error type with detailed context information.
 ```go
 type LuaError struct {
     Code       int
     Message    string
+    File       string
+    Line       int
+    StackTrace string
+    Context    string
 }
 ```
 
@@ -393,12 +432,62 @@ trace := L.GetStackTrace()
 fmt.Println(trace)
 ```
 
-### safeCall(f func() C.int) error
+### GetErrorInfo(context string) *LuaError
-Internal function that wraps a potentially dangerous C call with stack checking.
+Extracts detailed error information from the Lua stack.
 ```go
-err := s.safeCall(func() C.int {
+err := L.GetErrorInfo("MyFunction")
-    return C.lua_pcall(s.L, C.int(nargs), C.int(nresults), 0)
+```
-})
+
+### 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
@@ -423,9 +512,3 @@ L.PushString("hello")
 // ... use the string
 L.Pop(1)  // Clean up when done
 ```
-
-Sandbox management:
-```go
-sandbox := luajit.NewSandbox()
-defer sandbox.Close()
-```