luar

func Complex ¶

func Complex(L *lua.State) int

Complex pushes a proxy to a Go complex on the stack.

Arguments: real (number), imag (number)

Returns: proxy (complex128)

func GoToLua ¶

func GoToLua(L *lua.State, a interface{})

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.

package main

import (
	"fmt"

	"github.com/aarzilli/golua/lua"
	"github.com/stevedonovan/luar"
)

func main() {
	L := lua.NewState()
	defer L.Close()
	L.OpenLibs()

	input := "Hello world!"
	luar.GoToLua(L, input)
	L.SetGlobal("input")

	luar.GoToLua(L, fmt.Println)
	L.SetGlobal("print")
	L.DoString("print(input)")
}

Output:

Hello world!

func GoToLuaProxy ¶

func GoToLuaProxy(L *lua.State, a interface{})

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 ¶

func Init() *lua.State

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.

package main

import (
	"fmt"
	"strconv"

	"github.com/stevedonovan/luar"
)

func main() {
	const code = `
-- Lua tables auto-convert to slices in Go-function calls.
local res = foo {10, 20, 30, 40}

-- The result is a map-proxy.
print(res['1'], res['2'])

-- Which we may explicitly convert to a table.
res = luar.unproxify(res)
for k,v in pairs(res) do
	print(k,v)
end
`

	foo := func(args []int) (res map[string]int) {
		res = make(map[string]int)
		for i, val := range args {
			res[strconv.Itoa(i)] = val * val
		}
		return
	}

	L := luar.Init()
	defer L.Close()

	luar.Register(L, "", luar.Map{
		"foo":   foo,
		"print": fmt.Println,
	})

	res := L.DoString(code)
	if res != nil {
		fmt.Println("Error:", res)
	}
}

Output:

400 900
1 400
0 100
3 1600
2 900

func LuaToGo ¶

func LuaToGo(L *lua.State, idx int, a interface{}) error

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 ¶

func MakeChan(L *lua.State) int

MakeChan creates a 'chan interface{}' proxy and pushes it on the stack.

Optional argument: size (number)

Returns: proxy (chan interface{})

package main

import (
	"fmt"
	"log"
	"sync"

	"github.com/stevedonovan/luar"
)

func main() {
	L1 := luar.Init()
	defer L1.Close()
	L2 := luar.Init()
	defer L2.Close()

	luar.MakeChan(L1)
	L1.SetGlobal("c")
	L1.GetGlobal("c")
	var c interface{}
	err := luar.LuaToGo(L1, -1, &c)
	L1.Pop(1)
	if err != nil {
		log.Fatal(err)
	}

	luar.Register(L2, "", luar.Map{"c": c})
	var wg sync.WaitGroup
	wg.Add(1)

	go func() {
		err := L1.DoString(`c.send(17)`)
		if err != nil {
			fmt.Println(err)
		}
		wg.Done()
	}()

	err = L2.DoString(`return c.recv()`)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(L2.ToNumber(-1))
	L2.Pop(1)
	wg.Wait()
}

Output:

17

func MakeMap ¶

func MakeMap(L *lua.State) int

MakeMap creates a 'map[string]interface{}' proxy and pushes it on the stack.

Returns: proxy (map[string]interface{})

func MakeSlice ¶

func MakeSlice(L *lua.State) int

MakeSlice creates a '[]interface{}' proxy and pushes it on the stack.

Optional argument: size (number)

Returns: proxy ([]interface{})

func ProxyIpairs ¶

func ProxyIpairs(L *lua.State) int

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 ¶

func ProxyMethod(L *lua.State) int

ProxyMethod pushes the proxy method on the stack.

Argument: proxy

Returns: method (function)

func ProxyPairs ¶

func ProxyPairs(L *lua.State) int

ProxyPairs implements Lua 5.2 'pairs' functions. It respects the __pairs metamethod.

It is only useful for compatibility with Lua 5.1.

func ProxyType ¶

func ProxyType(L *lua.State) int

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 ¶

func RegProxyIpairs(L *lua.State, table, name string)

Register a function 'table.name' equivalent to ProxyIpairs that uses 'ipairs' when '__ipairs' is not present.

This is much faster than ProxyIpairs.

func Register ¶

func Register(L *lua.State, table string, values Map)

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.

package main

import (
	"fmt"
	"log"

	"github.com/stevedonovan/luar"
)

func main() {
	const code = `
print("foo")
print(io ~= nil)
print(os == nil)
`

	L := luar.Init()
	defer L.Close()

	res := L.LoadString(code)
	if res != 0 {
		msg := L.ToString(-1)
		fmt.Println("could not compile", msg)
	}

	// Create a empty sandbox.
	L.NewTable()
	// "*" means "use table on top of the stack."
	luar.Register(L, "*", luar.Map{
		"print": fmt.Println,
	})
	env := luar.NewLuaObject(L, -1)
	G := luar.NewLuaObjectFromName(L, "_G")
	defer env.Close()
	defer G.Close()

	// We can copy any Lua object from "G" to env with 'Set', e.g.:
	//   env.Set("print", G.Get("print"))
	// A more convenient and efficient way is to do a bulk copy with 'Setv':
	env.Setv(G, "type", "io", "table")

	// Set up sandbox.
	L.SetfEnv(-2)

	// Run 'code' chunk.
	err := L.Call(0, 0)
	if err != nil {
		log.Fatal(err)
	}
}

Output:

foo
true
true

func Unproxify ¶

func Unproxify(L *lua.State) int

Unproxify converts a proxy to an unproxified Lua value.

Argument: proxy

Returns: value (Lua value)