GopherLua: VM and compiler for Lua in Go.

Join the chat at https://gitter.im/yuin/gopher-lua

GopherLua is a Lua5.1 VM and compiler written in Go. GopherLua has a same goal with Lua: Be a scripting language with extensible semantics . It provides Go APIs that allow you to easily embed a scripting language to your Go host programs.

Contents

Design principle
How about performance?
Installation
Usage
Differences between Lua and GopherLua
Standalone interpreter
How to Contribute
Libraries for GopherLua
License
Author

Design principle

Be a scripting language with extensible semantics.
User-friendly Go API
- The stack based API like the one used in the original Lua implementation will cause a performance improvements in GopherLua (It will reduce memory allocations and concrete type <-> interface conversions). GopherLua API is not the stack based API. GopherLua give preference to the user-friendliness over the performance.

How about performance?

GopherLua is not fast but not too slow, I think.

There are some benchmarks on the wiki page .

Installation

go get github.com/yuin/gopher-lua

GopherLua supports >= Go1.4.

Usage

GopherLua APIs perform in much the same way as Lua, but the stack is used only for passing arguments and receiving returned values.

GopherLua supports channel operations. See "Goroutines" section.

Import a package.

import (
    "github.com/yuin/gopher-lua"
)

Run scripts in the VM.

L := lua.NewState()
defer L.Close()
if err := L.DoString(`print("hello")`); err != nil {
    panic(err)
}

L := lua.NewState()
defer L.Close()
if err := L.DoFile("hello.lua"); err != nil {
    panic(err)
}

Refer to Lua Reference Manual and Go doc for further information.

Note that elements that are not commented in Go doc equivalent to Lua Reference Manual , except GopherLua uses objects instead of Lua stack indcies.

Data model

All data in a GopherLua program is an LValue . LValue is an interface type that has following methods.

String() string
Type() LValueType

Objects implement an LValue interface are

Type name	Go type	Type() value	Constants
`LNilType`	(constants)	`LTNil`	`LNil`
`LBool`	(constants)	`LTBool`	`LTrue`, `LFalse`
`LNumber`	float64	`LTNumber`	`-`
`LString`	string	`LTString`	`-`
`LFunction`	struct pointer	`LTFunction`	`-`
`LUserData`	struct pointer	`LTUserData`	`-`
`LState`	struct pointer	`LTThread`	`-`
`LTable`	struct pointer	`LTTable`	`-`
`LChannel`	chan LValue	`LTChannel`	`-`

You can test an object type in Go way(type assertion) or using a Type() value.

lv := L.Get(-1) // get the value at the top of the stack
if str, ok := lv.(lua.LString); ok {
    // lv is LString
    fmt.Println(string(str))
}
if lv.Type() != lua.LTString {
    panic("string required.")
}

lv := L.Get(-1) // get the value at the top of the stack
if tbl, ok := lv.(*lua.LTable); ok {
    // lv is LTable
    fmt.Println(L.ObjLen(tbl))
}

Note that LBool , LNumber , LString is not a pointer.

To test LNilType and LBool, You must use pre-defined constants.

lv := L.Get(-1) // get the value at the top of the stack

if lv == LTrue { // correct
}

if bl, ok == lv.(lua.LBool); ok && bool(bl) { // wrong
}

In Lua, both nil and false make a condition false. LVIsFalse and LVAsBool implement this specification.

lv := L.Get(-1) // get the value at the top of the stack
if LVIsFalse(lv) { // lv is nil or false
}

if LVAsBool(lv) { // lv is neither nil nor false
}

Objects that based on go structs(LFunction. LUserData, LTable) have some public methods and fields. You can use these methods and fields for performance and debugging, but there are some limitations.

Metatable does not work.
No error handlings.

Callstack & Registry size

Size of the callstack & registry is fixed for mainly performance. You can change the default size of the callstack & registry.

lua.RegistrySize = 1024 * 20
lua.CallStackSize = 1024
L := lua.NewState()
defer L.Close()

You can also create an LState object that has the callstack & registry size specified by Options .

L := lua.NewState(lua.Options{
    CallStackSize: 120,
    RegistrySize:  120*20,
})

An LState object that has been created by *LState#NewThread() inherits the callstack & registry size from the parent LState object.

Miscellaneous lua.NewState options

Options.SkipOpenLibs bool(default false)
- By default, GopherLua opens all built-in libraries when new LState is created.
- You can skip this behaviour by setting this to true .
Options.IncludeGoStackTrace bool(default false)
- By default, GopherLua does not show Go stack traces when panics occur.
- You can get Go stack traces by setting this to true .

API

Refer to Lua Reference Manual and Go doc(LState methods) for further information.

Calling Go from Lua

func Double(L *lua.LState) int {
    lv := L.ToInt(1)             /* get argument */
    L.Push(lua.LNumber(lv * 2)) /* push result */
    return 1                     /* number of results */
}

func main() {
    L := lua.NewState()
    defer L.Close()
    L.SetGlobal("double", L.NewFunction(Double)) /* Original lua_setglobal uses stack... */
}

print(double(20)) -- > "40"

Any function registered with GopherLua is a lua.LGFunction, defined in value.go

type LGFunction func(*LState) int

Working with coroutines.

co := L.NewThread() /* create a new thread */
fn := L.GetGlobal("coro").(*lua.LFunction) /* get function from lua */
for {
    st, err, values := L.Resume(co, fn)
    if st == lua.ResumeError {
        fmt.Println("yield break(error)")
        fmt.Println(err.Error())
        break
    }

    for i, lv := range values {
        fmt.Printf("%v : %v\n", i, lv)
    }

    if st == lua.ResumeOK {
        fmt.Println("yield break(ok)")
        break
    }
}

Creating a module by Go

mymodule.go

package mymodule

import (
    "github.com/yuin/gopher-lua"
)

func Loader(L *lua.LState) int {
    // register functions to the table
    mod := L.SetFuncs(L.NewTable(), exports)
    // register other stuff
    L.SetField(mod, "name", lua.LString("value"))

    // returns the module
    L.Push(mod)
    return 1
}

var exports = map[string]lua.LGFunction{
    "myfunc": myfunc,
}

func myfunc(L *lua.LState) int {
    return 0
}

mymain.go

package main

import (
    "./mymodule"
    "github.com/yuin/gopher-lua"
)

func main() {
    L := lua.NewState()
    defer L.Close()
    L.PreloadModule("mymodule", mymodule.Loader)
    if err := L.DoFile("main.lua"); err != nil {
        panic(err)
    }
}

main.lua

local m = require("mymodule")
m.myfunc()
print(m.name)

Calling Lua from Go

L := lua.NewState()
defer L.Close()
if err := L.DoFile("double.lua"); err != nil {
    panic(err)
}
if err := L.CallByParam(lua.P{
    Fn: L.GetGlobal("double"),
    NRet: 1,
    Protect: true,
    }, lua.LNumber(10)); err != nil {
    panic(err)
}
ret := L.Get(-1) // returned value
L.Pop(1)  // remove received value

If Protect is false, GopherLua will panic instead of returning an error value.

User-Defined types

You can extend GopherLua with new types written in Go. LUserData is provided for this purpose.

type Person struct {
    Name string
}

const luaPersonTypeName = "person"

// Registers my person type to given L.
func registerPersonType(L *lua.LState) {
    mt := L.NewTypeMetatable(luaPersonTypeName)
    L.SetGlobal("person", mt)
    // static attributes
    L.SetField(mt, "new", L.NewFunction(newPerson))
    // methods
    L.SetField(mt, "__index", L.SetFuncs(L.NewTable(), personMethods))
}

// Constructor
func newPerson(L *lua.LState) int {
    person := &Person{L.CheckString(1)}
    ud := L.NewUserData()
    ud.Value = person
    L.SetMetatable(ud, L.GetTypeMetatable(luaPersonTypeName))
    L.Push(ud)
    return 1
}

// Checks whether the first lua argument is a *LUserData with *Person and returns this *Person.
func checkPerson(L *lua.LState) *Person {
    ud := L.CheckUserData(1)
    if v, ok := ud.Value.(*Person); ok {
        return v
    }
    L.ArgError(1, "person expected")
    return nil
}

var personMethods = map[string]lua.LGFunction{
    "name": personGetSetName,
}

// Getter and setter for the Person#Name
func personGetSetName(L *lua.LState) int {
    p := checkPerson(L)
    if L.GetTop() == 2 {
        p.Name = L.CheckString(2)
        return 0
    }
    L.Push(lua.LString(p.Name))
    return 1
}

func main() {
    L := lua.NewState()
    defer L.Close()
    registerPersonType(L)
    if err := L.DoString(`
        p = person.new("Steeve")
        print(p:name()) -- "Steeve"
        p:name("Alice")
        print(p:name()) -- "Alice"
    `); err != nil {
        panic(err)
    }
}

Goroutines

The LState is not goroutine-safe. It is recommended to use one LState per goroutine and communicate between goroutines by using channels.

Channels are represented by channel objects in GopherLua. And a channel table provides functions for performing channel operations.

Some objects can not be sent over channels due to having non-goroutine-safe objects inside itself.

a thread(state)
a function
an userdata
a table with a metatable

You must not send these objects from Go APIs to channels.

func receiver(ch, quit chan lua.LValue) {
    L := lua.NewState()
    defer L.Close()
    L.SetGlobal("ch", lua.LChannel(ch))
    L.SetGlobal("quit", lua.LChannel(quit))
    if err := L.DoString(`
    local exit = false
    while not exit do
      channel.select(
        {"|<-", ch, function(ok, v)
          if not ok then
            print("channel closed")
            exit = true
          else
            print("received:", v)
          end
        end},
        {"|<-", quit, function(ok, v)
            print("quit")
            exit = true
        end}
      )
    end
  `); err != nil {
        panic(err)
    }
}

func sender(ch, quit chan lua.LValue) {
    L := lua.NewState()
    defer L.Close()
    L.SetGlobal("ch", lua.LChannel(ch))
    L.SetGlobal("quit", lua.LChannel(quit))
    if err := L.DoString(`
    ch:send("1")
    ch:send("2")
  `); err != nil {
        panic(err)
    }
    ch <- lua.LString("3")
    quit <- lua.LTrue
}

func main() {
    ch := make(chan lua.LValue)
    quit := make(chan lua.LValue)
    go receiver(ch, quit)
    go sender(ch, quit)
    time.Sleep(3 * time.Second)
}

Go API

ToChannel, CheckChannel, OptChannel are available.

Refer to Go doc(LState methods) for further information.

Lua API

channel.make([buf:int]) -> ch:channel
- Create new channel that has a buffer size of buf. By default, buf is 0.
channel.select(case:table [, case:table, case:table ...]) -> {index:int, recv:any, ok}
- Same as the select statement in Go. It returns the index of the chosen case and, if that case was a receive operation, the value received and a boolean indicating whether the channel has been closed.
- case is a table that outlined below.
  
  receiving: {"|<-", ch:channel [, handler:func(ok, data:any)]}
  
  sending: {"<-|", ch:channel, data:any [, handler:func(data:any)]}
  
  default: {"default" [, handler:func()]}

channel.select examples:

local idx, recv, ok = channel.select(
  {"|<-", ch1},
  {"|<-", ch2}
)
if not ok then
    print("closed")
elseif idx == 1 then -- received from ch1
    print(recv)
elseif idx == 2 then -- received from ch2
    print(recv)
end

channel.select(
  {"|<-", ch1, function(ok, data)
    print(ok, data)
  end},
  {"<-|", ch2, "value", function(data)
    print(data)
  end},
  {"default", function()
    print("default action")
  end}
)

channel:send(data:any)
- Send data over the channel.
channel:receive() -> ok:bool, data:any
- Receive some data over the channel.
channel:close()
- Close the channel.

The LState pool pattern

To create per-thread LState instances, You can use the sync.Pool like mechanism.

type lStatePool struct {
    m     sync.Mutex
    saved []*lua.LState
}

func (pl *lStatePool) Get() *lua.LState {
    pl.m.Lock()
    defer pl.m.Unlock()
    n := len(pl.saved)
    if n == 0 {
        return pl.New()
    }
    x := pl.saved[n-1]
    pl.saved = pl.saved[0 : n-1]
    return x
}

func (pl *lStatePool) New() *lua.LState {
    L := lua.NewState()
    // setting the L up here.
    // load scripts, set global variables, share channels, etc...
    return L
}

func (pl *lStatePool) Put(L *lua.LState) {
    pl.m.Lock()
    defer pl.m.Unlock()
    pl.saved = append(pl.saved, L)
}

func (pl *lStatePool) Shutdown() {
    for _, L := range pl.saved {
        L.Close()
    }
}

// Global LState pool
var luaPool = &lStatePool{
    saved: make([]*lua.LState, 0, 4),
}

Now, you can get per-thread LState objects from the luaPool .

func MyWorker() {
   L := luaPool.Get()
   defer luaPool.Put(L)
   /* your code here */
}

func main() {
    defer luaPool.Shutdown()
    go MyWorker()
    go MyWorker()
    /* etc... */
}

Differences between Lua and GopherLua

Goroutines

GopherLua supports channel operations.
- GopherLua has a type named channel.
- The channel table provides functions for performing channel operations.

Unsupported functions

string.dump
os.setlocale
collectgarbage
lua_Debug.namewhat
package.loadlib
debug hooks

Miscellaneous notes

file:setvbuf does not support a line buffering.
Daylight saving time is not supported.
GopherLua has a function to set an environment variable : os.setenv(name, value)

Standalone interpreter

Lua has an interpreter called lua . GopherLua has an interpreter called glua .

go get github.com/yuin/gopher-lua/cmd/glua

glua has same options as lua .

How to Contribute

Any kind of contributions are welcome.

Building GopherLua

GopherLua uses simple inlining tool for generate efficient codes. This tool requires python interpreter. Files name of which starts with _ genarate files name of which does not starts with _ . For instance, _state.go generate state.go . You do not edit generated sources. To generate sources, some make target is available.

make build
make glua
make test

You have to run make build before committing to the repository.

Pull requests

Our workflow is based on the github-flow .

Create a new issue.
Fork the project.

Clone your fork and add the upstream.

git remote add upstream https://github.com/yuin/gopher-lua.git

Pull new changes from the upstream.

git checkout master
git fetch upstream
git merge upstream/master

Create a feature branch
```
git checkout -b <branch-name>
```
Commit your changes and reference the issue number in your comment.
```
git commit -m "Issue #<issue-ref> : <your message>"
```
Push the feature branch to your remote repository.
```
git push origin <branch-name>
```
Open new pull request.

Libraries for GopherLua

gopher-luar : Custom type reflection for gopher-lua
gluamapper : Mapping a Lua table to a Go struct
gluare : Regular expressions for gopher-lua
gluahttp : HTTP request module for gopher-lua
gopher-json : A simple JSON encoder/decoder for gopher-lua
gluayaml : Yaml parser for gopher-lua
glua-lfs : Partially implements the luafilesystem module for gopher-lua
gluaurl : A url parser/builder module for gopher-lua

License

MIT

Author

Yusuke Inuzuka

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.rst

README.rst

GopherLua: VM and compiler for Lua in Go.

Design principle

How about performance?

Installation

Usage

Data model

Callstack & Registry size

Miscellaneous lua.NewState options

API

Calling Go from Lua

Creating a module by Go

Calling Lua from Go

User-Defined types

Goroutines

Go API

Lua API

The LState pool pattern

Differences between Lua and GopherLua

Goroutines

Unsupported functions

Miscellaneous notes

Standalone interpreter

How to Contribute

Building GopherLua

Pull requests

Libraries for GopherLua

License

Author

Files

README.rst

Latest commit

History

README.rst

File metadata and controls

GopherLua: VM and compiler for Lua in Go.

Data model

Callstack & Registry size

Miscellaneous lua.NewState options

API

Calling Go from Lua

Creating a module by Go

Calling Lua from Go

User-Defined types

Goroutines

Go API

Lua API

The LState pool pattern

Goroutines

Unsupported functions

Miscellaneous notes

Building GopherLua

Pull requests