Sky/LuaJIT-to-Go
1
0
Fork 0
Code Issues Pull Requests Releases 11 Activity

update documentation

Browse Source
This commit is contained in:
Sky Johnson 2025-05-31 17:49:25 -05:00
parent f4bfff470f
commit 202664f635
2 changed files with 203 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
API.md Normal file
View File

@ -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

155
DOCS.md
View File

@ -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
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()
```