search

aarzilli / golua

Go bindings for Lua C API - in progress
MIT License
651 stars 160 forks source link

readme

Go Bindings for the lua C API

Build Status

Simplest way to install:

# go get github.com/aarzilli/golua/lua

You can then try to run the examples:

$ cd golua/_example/
$ go run basic.go
$ go run alloc.go
$ go run panic.go
$ go run userdata.go

This library is configured using build tags. By default it will look for a library (or "shared object") called:

If this doesn't work -tags luadash5.1 can be used to force lua-5.1, and -tags llua can be used to force lua.

If you want to statically link to liblua.a you can do that with -tags luaa. Luajit can also be used by specifying -tags luajit.

The library uses lua5.1 by default but also supports lua5.2 by specifying -tags lua52, lua5.3 by specifying -tags lua53, and lua5.4 by specifying -tags lua54. If the library installed on your system has a dash, for example it is called liblua-5.4 use the lluadash tag: go build -tags lua54,lluadash ....

QUICK START

Create a new Virtual Machine with:

L := lua.NewState()
L.OpenLibs()
defer L.Close()

Lua's Virtual Machine is stack based, you can call lua functions like this:

// push "print" function on the stack
L.GetGlobal("print")
// push the string "Hello World!" on the stack
L.PushString("Hello World!")
// call print with one argument, expecting no results
L.Call(1, 0)

Of course this isn't very useful, more useful is executing lua code from a file or from a string:

// executes a string of lua code
err := L.DoString("...")
// executes a file
err = L.DoFile(filename)

You will also probably want to publish go functions to the virtual machine, you can do it by:

func adder(L *lua.State) int {
    a := L.ToInteger(1)
    b := L.ToInteger(2)
    L.PushInteger(a + b)
    return 1 // number of return values
}

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

    L.Register("adder", adder)
    L.DoString("print(adder(2, 2))")
}

ON ERROR HANDLING

Lua's exceptions are incompatible with Go, golua works around this incompatibility by setting up protected execution environments in lua.State.DoString, lua.State.DoFile and lua.State.Call and turning every exception into a Go panic.

This means that:

  1. In general you can't do any exception handling from Lua, pcall and xpcall are renamed to unsafe_pcall and unsafe_xpcall. They are only safe to be called from Lua code that never calls back to Go. Use at your own risk.

  2. The call to lua.State.Error, present in previous versions of this library, has been removed as it is nonsensical

  3. Method calls on a newly created lua.State happen in an unprotected environment, if Lua throws an exception as a result your program will be terminated. If this is undesirable perform your initialization like this:

func LuaStateInit(L *lua.State) int {
    … initialization goes here…
    return 0
}

…
L.PushGoFunction(LuaStateInit)
err := L.Call(0, 0)
…

ON THREADS AND COROUTINES

'lua.State' is not thread safe, but the library itself is. Lua's coroutines exist but (to my knowledge) have never been tested and are likely to encounter the same problems that errors have, use at your own peril.

ODDS AND ENDS

LUAJIT

To link with luajit-2.0.x, you can use CGO_CFLAGS and CGO_LDFLAGS environment variables

$ CGO_CFLAGS=`pkg-config luajit --cflags`
$ CGO_LDFLAGS=`pkg-config luajit --libs-only-L`
$ go get -f -u -tags luajit github.com/aarzilli/golua/lua

CONTRIBUTORS

SEE ALSO

Licensing

GoLua is released under the MIT license. Please see the LICENSE file for more information.

Lua is Copyright (c) Lua.org, PUC-Rio. All rights reserved.