From 202664f6351fb224ff36f434ee2249e27c65ca08 Mon Sep 17 00:00:00 2001 From: Sky Johnson Date: Sat, 31 May 2025 17:49:25 -0500 Subject: [PATCH] update documentation --- API.md | 82 +++++++++++++++++++++++++++++ DOCS.md | 159 ++++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 203 insertions(+), 38 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..294f1f1 --- /dev/null +++ b/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 diff --git a/DOCS.md b/DOCS.md index f877387..e6d1b17 100644 --- a/DOCS.md +++ b/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) -Converts a Lua table to a Go map. +### ToTable(index int) (any, error) +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) -``` - -### PushTable(table map[string]any) error -Pushes a Go map as a Lua table. -```go -data := map[string]any{ +// Supports: primitives, slices, maps with various type combinations +err := L.PushValue(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 + 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 -Internal function that wraps a potentially dangerous C call with stack checking. +### GetErrorInfo(context string) *LuaError +Extracts detailed error information from the Lua stack. ```go -err := s.safeCall(func() C.int { - return C.lua_pcall(s.L, C.int(nargs), C.int(nresults), 0) -}) +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 @@ -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() -```