Documentation
¶
Index ¶
- Variables
- func Complex(L *lua.State) int
- func GoToLua(L *lua.State, a interface{})
- func GoToLuaProxy(L *lua.State, a interface{})
- func Init() *lua.State
- func LuaToGo(L *lua.State, idx int, a interface{}) error
- func MakeChan(L *lua.State) int
- func MakeMap(L *lua.State) int
- func MakeSlice(L *lua.State) int
- func ProxyIpairs(L *lua.State) int
- func ProxyMethod(L *lua.State) int
- func ProxyPairs(L *lua.State) int
- func ProxyType(L *lua.State) int
- func RegProxyIpairs(L *lua.State, table, name string)
- func Register(L *lua.State, table string, values Map)
- func Unproxify(L *lua.State) int
- type ConvError
- type LuaObject
- func (lo *LuaObject) Call(results interface{}, args ...interface{}) error
- func (lo *LuaObject) Close()
- func (lo *LuaObject) Get(a interface{}, subfields ...interface{}) error
- func (lo *LuaObject) GetObject(subfields ...interface{}) (*LuaObject, error)
- func (lo *LuaObject) Iter() (*LuaTableIter, error)
- func (lo *LuaObject) Push()
- func (lo *LuaObject) Set(a interface{}, subfields ...interface{}) error
- func (lo *LuaObject) Setv(src *LuaObject, keys ...string) error
- type LuaTableIter
- type Map
- type NullT
Constants ¶
This section is empty.
Variables ¶
var ( ErrLuaObjectCallResults = errors.New("results must be a pointer to pointer/slice/struct") ErrLuaObjectCallable = errors.New("LuaObject must be callable") ErrLuaObjectIndexable = errors.New("not indexable") )
var ErrTableConv = errors.New("some table elements could not be converted")
ErrTableConv arises when some table entries could not be converted. The table conversion result is usable. TODO: Work out a more relevant name. TODO: Should it be a type instead embedding the actual error?
var ( // Null is the definition of 'luar.null' which is used in place of 'nil' when // converting slices and structs. Null = NullT(0) )
Functions ¶
func Complex ¶
Complex pushes a proxy to a Go complex on the stack.
Arguments: real (number), imag (number)
Returns: proxy (complex128)
func GoToLua ¶
GoToLua pushes a Go value 'val' on the Lua stack.
It unboxes interfaces.
Pointers are followed recursively. Slices, structs and maps are copied over as tables.
func GoToLuaProxy ¶
GoToLuaProxy is like GoToLua but pushes a proxy on the Lua stack when it makes sense.
A proxy is a Lua userdata that wraps a Go value.
Proxies have several uses:
- Type checking in Go function calls, so variable of user-defined type are always profixied.
- Reflexive modification of the Go data straight from the Lua code. We only allow this for compound types.
- Call methods of user-defined types.
Predeclared scalar types are never proxified as they have no methods and we only allow compound types to be set reflexively.
Structs are always proxified since their type is always user-defined. If they they are not settable (e.g. not nested, not passed by reference, value of a map), then a copy is passed as a proxy (otherwise setting the fields from Lua would panic). This will not impact the corresponding Go value.
Arrays are only proxified if they are settable (so that the user can set the Go value from the Lua side) or if they are of a user-defined type (method calls or function parameters). If the type user-defined but the array is not settable, then a proxy of a copy is made, just as for structs.
Lua cannot dereference pointers and Go can only call methods over one level of indirection at maximum. Thus proxies wrap around values dereferenced up to the last pointer.
Go functions can be passed to Lua. If the parameters require several levels of indirections, the arguments will be converted automatically. Since proxies can only wrap around one level of indirection, functions modifying the value of the pointers after one level of indirection will have no effect.
func Init ¶
Init makes and initializes a new pre-configured Lua state.
It populates the 'luar' table with some helper functions/values:
method: ProxyMethod unproxify: Unproxify chan: MakeChan complex: MakeComplex map: MakeMap slice: MakeSlice null: Null
It replaces the 'pairs'/'ipairs' functions with ProxyPairs/ProxyIpairs respectively, so that __pairs/__ipairs can be used, Lua 5.2 style. It allows for looping over Go composite types and strings.
It also replaces the 'type' function with ProxyType.
It is not required for using the 'GoToLua' and 'LuaToGo' functions.
func LuaToGo ¶
LuaToGo converts the Lua value at index 'idx' to the Go value.
The Go value must be a non-nil pointer.
Conversions to strings and numbers are straightforward.
Lua 'nil' is converted to the zero value of the specified Go value.
If the Lua value is non-nil, pointers are dereferenced (multiple times if required) and the pointed value is the one that is set. If 'nil', then the Go pointer is set to 'nil'. To set a pointer's value to its zero value, use 'luar.null'.
The Go value can be an interface, in which case the type is inferred. When converting a table to an interface, the Go value is a []interface{} slice if all its elements are indexed consecutively from 1, or a map[string]interface{} otherwise.
Existing entries in maps and structs are kept. Arrays and slices are reset.
Nil maps and slices are automatically allocated.
Proxies are unwrapped to the Go value, if convertible. If both the proxy and the Go value are pointers, then the Go pointer will be set to the proxy pointer. Userdata that is not a proxy will be converted to a LuaObject if the Go value is an interface or a LuaObject.
func MakeChan ¶
MakeChan creates a 'chan interface{}' proxy and pushes it on the stack.
Optional argument: size (number)
Returns: proxy (chan interface{})
func MakeMap ¶
MakeMap creates a 'map[string]interface{}' proxy and pushes it on the stack.
Returns: proxy (map[string]interface{})
func MakeSlice ¶
MakeSlice creates a '[]interface{}' proxy and pushes it on the stack.
Optional argument: size (number)
Returns: proxy ([]interface{})
func ProxyIpairs ¶
ProxyIpairs implements Lua 5.2 'ipairs' functions. It respects the __ipairs metamethod.
It is only useful for compatibility with Lua 5.1.
Because it cannot call 'ipairs' for it might recurse infinitely, ProxyIpairs reimplements `ipairsAux` in Go which can be a performance issue in tight loops.
You should call 'RegProxyIpairs' instead.
func ProxyMethod ¶
ProxyMethod pushes the proxy method on the stack.
Argument: proxy
Returns: method (function)
func ProxyPairs ¶
ProxyPairs implements Lua 5.2 'pairs' functions. It respects the __pairs metamethod.
It is only useful for compatibility with Lua 5.1.
func ProxyType ¶
ProxyType pushes the proxy type on the stack.
It behaves like Lua's "type" except for proxies for which it returns 'table<TYPE>', 'string<TYPE>' or 'number<TYPE>' with TYPE being the go type.
Argument: proxy
Returns: type (string)
func RegProxyIpairs ¶
Register a function 'table.name' equivalent to ProxyIpairs that uses 'ipairs' when '__ipairs' is not present.
This is much faster than ProxyIpairs.
func Register ¶
Register makes a number of Go values available in Lua code as proxies. 'values' is a map of strings to Go values.
- If table is non-nil, then create or reuse a global table of that name and put the values in it.
- If table is ” then put the values in the global table (_G).
- If table is '*' then assume that the table is already on the stack.
See GoToLuaProxy's documentation.
Types ¶
type ConvError ¶
type ConvError struct {
From interface{}
To interface{}
}
ConvError records a conversion error from value 'From' to value 'To'.
type LuaObject ¶
type LuaObject struct {
// contains filtered or unexported fields
}
LuaObject encapsulates a Lua object like a table or a function.
We do not make the type distinction since metatables can make tables callable and functions indexable.
func NewLuaObject ¶
NewLuaObject creates a new LuaObject from stack index.
func NewLuaObjectFromName ¶
NewLuaObjectFromName creates a new LuaObject from the object designated by the sequence of 'subfields'.
func NewLuaObjectFromValue ¶
NewLuaObjectFromValue creates a new LuaObject from a Go value. Note that this will convert any slices or maps into Lua tables.
func (*LuaObject) Call ¶
Call calls a Lua function, given the desired results and the arguments. 'results' must be a pointer to a pointer/struct/slice.
- If a pointer, then only the first result is stored to that pointer.
- If a struct with 'n' exported fields, then the first 'n' results are stored in the first 'n' exported fields.
- If a slice, then all the results are stored in the slice. The slice is re-allocated if necessary.
If the function returns more values than can be stored in the 'results' argument, they will be ignored.
If 'results' is nil, results will be discarded.
func (*LuaObject) Close ¶
func (lo *LuaObject) Close()
Close frees the Lua reference of this object.
func (*LuaObject) Get ¶
Get stores in 'a' the Lua value indexed at the sequence of 'subfields'. 'a' must be a pointer as in LuaToGo.
func (*LuaObject) GetObject ¶
GetObject returns the LuaObject indexed at the sequence of 'subfields'.
func (*LuaObject) Iter ¶
func (lo *LuaObject) Iter() (*LuaTableIter, error)
Iter creates a Lua iterator.
type LuaTableIter ¶
type LuaTableIter struct {
// contains filtered or unexported fields
}
LuaTableIter is the Go equivalent of a Lua table iterator.
func (*LuaTableIter) Error ¶
func (ti *LuaTableIter) Error() error
Error returns the error that happened during last iteration, if any.
func (*LuaTableIter) Next ¶
func (ti *LuaTableIter) Next(key, value interface{}) bool
Next gets the next key/value pair from the indexable value.
'value' must be a valid argument for LuaToGo. As a special case, 'value' can be nil to make it possible to loop over keys without caring about associated values.
Source Files