README
=============================================================================== GopherLua: VM and compiler for Lua in Go. =============================================================================== .. image:: https://godoc.org/github.com/yuin/gopher-lua?status.svg :target: http://godoc.org/github.com/yuin/gopher-lua .. image:: https://travis-ci.org/yuin/gopher-lua.svg :target: https://travis-ci.org/yuin/gopher-lua .. image:: https://coveralls.io/repos/yuin/gopher-lua/badge.svg :target: https://coveralls.io/r/yuin/gopher-lua .. image:: https://badges.gitter.im/Join%20Chat.svg :alt: Join the chat at https://gitter.im/yuin/gopher-lua :target: https://gitter.im/yuin/gopher-lua?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge | 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:: :depth: 1 ---------------------------------------------------------------- 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. GopherLua has almost equivalent ( or little bit better ) performance as Python3 on micro benchmarks. There are some benchmarks on the `wiki page <https://github.com/yuin/gopher-lua/wiki/Benchmarks>`_ . ---------------------------------------------------------------- Installation ---------------------------------------------------------------- .. code-block:: bash go get github.com/yuin/gopher-lua GopherLua supports >= Go1.9. ---------------------------------------------------------------- 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. .. code-block:: go import ( "github.com/yuin/gopher-lua" ) Run scripts in the VM. .. code-block:: go L := lua.NewState() defer L.Close() if err := L.DoString(`print("hello")`); err != nil { panic(err) } .. code-block:: go L := lua.NewState() defer L.Close() if err := L.DoFile("hello.lua"); err != nil { panic(err) } Refer to `Lua Reference Manual <http://www.lua.org/manual/5.1/>`_ and `Go doc <http://godoc.org/github.com/yuin/gopher-lua>`_ for further information. Note that elements that are not commented in `Go doc <http://godoc.org/github.com/yuin/gopher-lua>`_ equivalent to `Lua Reference Manual <http://www.lua.org/manual/5.1/>`_ , except GopherLua uses objects instead of Lua stack indices. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. .. code-block:: go 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.") } .. code-block:: go 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. .. code-block:: go lv := L.Get(-1) // get the value at the top of the stack if lv == lua.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. .. code-block:: go lv := L.Get(-1) // get the value at the top of the stack if lua.LVIsFalse(lv) { // lv is nil or false } if lua.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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The size of an ``LState``'s callstack controls the maximum call depth for Lua functions within a script (Go function calls do not count). The registry of an ``LState`` implements stack storage for calling functions (both Lua and Go functions) and also for temporary variables in expressions. Its storage requirements will increase with callstack usage and also with code complexity. Both the registry and the callstack can be set to either a fixed size or to auto size. When you have a large number of ``LStates`` instantiated in a process, it's worth taking the time to tune the registry and callstack options. +++++++++ Registry +++++++++ The registry can have an initial size, a maximum size and a step size configured on a per ``LState`` basis. This will allow the registry to grow as needed. It will not shrink again after growing. .. code-block:: go L := lua.NewState(lua.Options{ RegistrySize: 1024 * 20, // this is the initial size of the registry RegistryMaxSize: 1024 * 80, // this is the maximum size that the registry can grow to. If set to `0` (the default) then the registry will not auto grow RegistryGrowStep: 32, // this is how much to step up the registry by each time it runs out of space. The default is `32`. }) defer L.Close() A registry which is too small for a given script will ultimately result in a panic. A registry which is too big will waste memory (which can be significant if many ``LStates`` are instantiated). Auto growing registries incur a small performance hit at the point they are resized but will not otherwise affect performance. +++++++++ Callstack +++++++++ The callstack can operate in two different modes, fixed or auto size. A fixed size callstack has the highest performance and has a fixed memory overhead. An auto sizing callstack will allocate and release callstack pages on demand which will ensure the minimum amount of memory is in use at any time. The downside is it will incur a small performance impact every time a new page of callframes is allocated. By default an ``LState`` will allocate and free callstack frames in pages of 8, so the allocation overhead is not incurred on every function call. It is very likely that the performance impact of an auto resizing callstack will be negligible for most use cases. .. code-block:: go L := lua.NewState(lua.Options{ CallStackSize: 120, // this is the maximum callstack size of this LState MinimizeStackMemory: true, // Defaults to `false` if not specified. If set, the callstack will auto grow and shrink as needed up to a max of `CallStackSize`. If not set, the callstack will be fixed at `CallStackSize`. }) defer L.Close() ++++++++++++++++ Option defaults ++++++++++++++++ The above examples show how to customize the callstack and registry size on a per ``LState`` basis. You can also adjust some defaults for when options are not specified by altering the values of ``lua.RegistrySize``, ``lua.RegistryGrowStep`` and ``lua.CallStackSize``. 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`` . - Using the various `OpenXXX(L *LState) int` functions you can open only those libraries that you require, for an example see below. - **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 <http://www.lua.org/manual/5.1/>`_ and `Go doc(LState methods) <http://godoc.org/github.com/yuin/gopher-lua>`_ for further information. +++++++++++++++++++++++++++++++++++++++++ Calling Go from Lua +++++++++++++++++++++++++++++++++++++++++ .. code-block:: go 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... */ } .. code-block:: lua print(double(20)) -- > "40" Any function registered with GopherLua is a ``lua.LGFunction``, defined in ``value.go`` .. code-block:: go type LGFunction func(*LState) int Working with coroutines. .. code-block:: go 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 } } +++++++++++++++++++++++++++++++++++++++++ Opening a subset of builtin modules +++++++++++++++++++++++++++++++++++++++++ The following demonstrates how to open a subset of the built-in modules in Lua, say for example to avoid enabling modules with access to local files or system calls. main.go .. code-block:: go func main() { L := lua.NewState(lua.Options{SkipOpenLibs: true}) defer L.Close() for _, pair := range []struct { n string f lua.LGFunction }{ {lua.LoadLibName, lua.OpenPackage}, // Must be first {lua.BaseLibName, lua.OpenBase}, {lua.TabLibName, lua.OpenTable}, } { if err := L.CallByParam(lua.P{ Fn: L.NewFunction(pair.f), NRet: 0, Protect: true, }, lua.LString(pair.n)); err != nil { panic(err) } } if err := L.DoFile("main.lua"); err != nil { panic(err) } } +++++++++++++++++++++++++++++++++++++++++ Creating a module by Go +++++++++++++++++++++++++++++++++++++++++ mymodule.go .. code-block:: 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 .. code-block:: 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 .. code-block:: lua local m = require("mymodule") m.myfunc() print(m.name) +++++++++++++++++++++++++++++++++++++++++ Calling Lua from Go +++++++++++++++++++++++++++++++++++++++++ .. code-block:: 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. .. code-block:: go 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) } } +++++++++++++++++++++++++++++++++++++++++ Terminating a running LState +++++++++++++++++++++++++++++++++++++++++ GopherLua supports the `Go Concurrency Patterns: Context <https://blog.golang.org/context>`_ . .. code-block:: go L := lua.NewState() defer L.Close() ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second) defer cancel() // set the context to our LState L.SetContext(ctx) err := L.DoString(` local clock = os.clock function sleep(n) -- seconds local t0 = clock() while clock() - t0 <= n do end end sleep(3) `) // err.Error() contains "context deadline exceeded" With coroutines .. code-block:: go L := lua.NewState() defer L.Close() ctx, cancel := context.WithCancel(context.Background()) L.SetContext(ctx) defer cancel() L.DoString(` function coro() local i = 0 while true do coroutine.yield(i) i = i+1 end return i end `) co, cocancel := L.NewThread() defer cocancel() fn := L.GetGlobal("coro").(*LFunction) _, err, values := L.Resume(co, fn) // err is nil cancel() // cancel the parent context _, err, values = L.Resume(co, fn) // err is NOT nil : child context was canceled **Note that using a context causes performance degradation.** .. code-block:: time ./glua-with-context.exe fib.lua 9227465 0.01s user 0.11s system 1% cpu 7.505 total time ./glua-without-context.exe fib.lua 9227465 0.01s user 0.01s system 0% cpu 5.306 total +++++++++++++++++++++++++++++++++++++++++ Sharing Lua byte code between LStates +++++++++++++++++++++++++++++++++++++++++ Calling ``DoFile`` will load a Lua script, compile it to byte code and run the byte code in a ``LState``. If you have multiple ``LStates`` which are all required to run the same script, you can share the byte code between them, which will save on memory. Sharing byte code is safe as it is read only and cannot be altered by lua scripts. .. code-block:: go // CompileLua reads the passed lua file from disk and compiles it. func CompileLua(filePath string) (*lua.FunctionProto, error) { file, err := os.Open(filePath) defer file.Close() if err != nil { return nil, err } reader := bufio.NewReader(file) chunk, err := parse.Parse(reader, filePath) if err != nil { return nil, err } proto, err := lua.Compile(chunk, filePath) if err != nil { return nil, err } return proto, nil } // DoCompiledFile takes a FunctionProto, as returned by CompileLua, and runs it in the LState. It is equivalent // to calling DoFile on the LState with the original source file. func DoCompiledFile(L *lua.LState, proto *lua.FunctionProto) error { lfunc := L.NewFunctionFromProto(proto) L.Push(lfunc) return L.PCall(0, lua.MultRet, nil) } // Example shows how to share the compiled byte code from a lua script between multiple VMs. func Example() { codeToShare := CompileLua("mylua.lua") a := lua.NewState() b := lua.NewState() c := lua.NewState() DoCompiledFile(a, codeToShare) DoCompiledFile(b, codeToShare) DoCompiledFile(c, codeToShare) } +++++++++++++++++++++++++++++++++++++++++ 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. .. code-block:: go 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) <http://godoc.org/github.com/yuin/gopher-lua>`_ 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: .. code-block:: lua 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 .. code-block:: lua 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. .. code-block:: go 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`` . .. code-block:: go 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`` - ``lua_Debug.namewhat`` - ``package.loadlib`` - debug hooks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Miscellaneous notes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``collectgarbage`` does not take any arguments and runs the garbage collector for the entire Go program. - ``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`` . .. code-block:: bash go get github.com/yuin/gopher-lua/cmd/glua ``glua`` has same options as ``lua`` . ---------------------------------------------------------------- How to Contribute ---------------------------------------------------------------- See `Guidlines for contributors <https://github.com/yuin/gopher-lua/tree/master/.github/CONTRIBUTING.md>`_ . ---------------------------------------------------------------- Libraries for GopherLua ---------------------------------------------------------------- - `gopher-luar <https://github.com/layeh/gopher-luar>`_ : Simplifies data passing to and from gopher-lua - `gluamapper <https://github.com/yuin/gluamapper>`_ : Mapping a Lua table to a Go struct - `gluare <https://github.com/yuin/gluare>`_ : Regular expressions for gopher-lua - `gluahttp <https://github.com/cjoudrey/gluahttp>`_ : HTTP request module for gopher-lua - `gopher-json <https://github.com/layeh/gopher-json>`_ : A simple JSON encoder/decoder for gopher-lua - `gluayaml <https://github.com/kohkimakimoto/gluayaml>`_ : Yaml parser for gopher-lua - `glua-lfs <https://github.com/layeh/gopher-lfs>`_ : Partially implements the luafilesystem module for gopher-lua - `gluaurl <https://github.com/cjoudrey/gluaurl>`_ : A url parser/builder module for gopher-lua - `gluahttpscrape <https://github.com/felipejfc/gluahttpscrape>`_ : A simple HTML scraper module for gopher-lua - `gluaxmlpath <https://github.com/ailncode/gluaxmlpath>`_ : An xmlpath module for gopher-lua - `gmoonscript <https://github.com/rucuriousyet/gmoonscript>`_ : Moonscript Compiler for the Gopher Lua VM - `loguago <https://github.com/rucuriousyet/loguago>`_ : Zerolog wrapper for Gopher-Lua - `gluacrypto <https://github.com/tengattack/gluacrypto>`_ : A native Go implementation of crypto library for the GopherLua VM. - `gluasql <https://github.com/tengattack/gluasql>`_ : A native Go implementation of SQL client for the GopherLua VM. - `purr <https://github.com/leyafo/purr>`_ : A http mock testing tool. - `vadv/gopher-lua-libs <https://github.com/vadv/gopher-lua-libs>`_ : Some usefull libraries for GopherLua VM. - `gluaperiphery <https://github.com/BixData/gluaperiphery>`_ : A periphery library for the GopherLua VM (GPIO, SPI, I2C, MMIO, and Serial peripheral I/O for Linux). - `glua-async <https://github.com/CuberL/glua-async>`_ : An async/await implement for gopher-lua. - `gopherlua-debugger <https://github.com/edolphin-ydf/gopherlua-debugger>`_ : A debugger for gopher-lua ---------------------------------------------------------------- Donation ---------------------------------------------------------------- BTC: 1NEDSyUmo4SMTDP83JJQSWi1MvQUGGNMZB ---------------------------------------------------------------- License ---------------------------------------------------------------- MIT ---------------------------------------------------------------- Author ---------------------------------------------------------------- Yusuke Inuzuka
Documentation
Overview ¶
GopherLua: VM and compiler for Lua in Go
Index ¶
- Constants
- Variables
- func LVAsBool(v LValue) bool
- func LVAsString(v LValue) string
- func LVCanConvToString(v LValue) bool
- func LVIsFalse(v LValue) bool
- func OpenBase(L *LState) int
- func OpenChannel(L *LState) int
- func OpenCoroutine(L *LState) int
- func OpenDebug(L *LState) int
- func OpenIo(L *LState) int
- func OpenMath(L *LState) int
- func OpenOs(L *LState) int
- func OpenPackage(L *LState) int
- func OpenString(L *LState) int
- func OpenTable(L *LState) int
- func UpvalueIndex(i int) int
- type ApiError
- type ApiErrorType
- type CompileError
- type DbgCall
- type DbgLocalInfo
- type Debug
- type FunctionProto
- type Global
- type LBool
- type LChannel
- type LFunction
- type LGFunction
- type LNilType
- type LNumber
- type LState
- func (ls *LState) ArgError(n int, message string)
- func (ls *LState) Call(nargs, nret int)
- func (ls *LState) CallByParam(cp P, args ...LValue) error
- func (ls *LState) CallMeta(obj LValue, event string) LValue
- func (ls *LState) CheckAny(n int) LValue
- func (ls *LState) CheckBool(n int) bool
- func (ls *LState) CheckChannel(n int) chan LValue
- func (ls *LState) CheckFunction(n int) *LFunction
- func (ls *LState) CheckInt(n int) int
- func (ls *LState) CheckInt64(n int) int64
- func (ls *LState) CheckNumber(n int) LNumber
- func (ls *LState) CheckOption(n int, options []string) int
- func (ls *LState) CheckString(n int) string
- func (ls *LState) CheckTable(n int) *LTable
- func (ls *LState) CheckThread(n int) *LState
- func (ls *LState) CheckType(n int, typ LValueType)
- func (ls *LState) CheckTypes(n int, typs ...LValueType)
- func (ls *LState) CheckUserData(n int) *LUserData
- func (ls *LState) Close()
- func (ls *LState) Concat(values ...LValue) string
- func (ls *LState) Context() context.Context
- func (ls *LState) CreateTable(acap, hcap int) *LTable
- func (ls *LState) DoFile(path string) error
- func (ls *LState) DoString(source string) error
- func (ls *LState) Equal(lhs, rhs LValue) bool
- func (ls *LState) Error(lv LValue, level int)
- func (ls *LState) FindTable(obj *LTable, n string, size int) LValue
- func (ls *LState) ForEach(tb *LTable, cb func(LValue, LValue))
- func (ls *LState) GPCall(fn LGFunction, data LValue) error
- func (ls *LState) Get(idx int) LValue
- func (ls *LState) GetFEnv(obj LValue) LValue
- func (ls *LState) GetField(obj LValue, skey string) LValue
- func (ls *LState) GetGlobal(name string) LValue
- func (ls *LState) GetInfo(what string, dbg *Debug, fn LValue) (LValue, error)
- func (ls *LState) GetLocal(dbg *Debug, no int) (string, LValue)
- func (ls *LState) GetMetaField(obj LValue, event string) LValue
- func (ls *LState) GetMetatable(obj LValue) LValue
- func (ls *LState) GetStack(level int) (*Debug, bool)
- func (ls *LState) GetTable(obj LValue, key LValue) LValue
- func (ls *LState) GetTop() int
- func (ls *LState) GetTypeMetatable(typ string) LValue
- func (ls *LState) GetUpvalue(fn *LFunction, no int) (string, LValue)
- func (ls *LState) Insert(value LValue, index int)
- func (ls *LState) IsClosed() bool
- func (ls *LState) LessThan(lhs, rhs LValue) bool
- func (ls *LState) Load(reader io.Reader, name string) (*LFunction, error)
- func (ls *LState) LoadFile(path string) (*LFunction, error)
- func (ls *LState) LoadString(source string) (*LFunction, error)
- func (ls *LState) NewClosure(fn LGFunction, upvalues ...LValue) *LFunction
- func (ls *LState) NewFunction(fn LGFunction) *LFunction
- func (ls *LState) NewFunctionFromProto(proto *FunctionProto) *LFunction
- func (ls *LState) NewTable() *LTable
- func (ls *LState) NewThread() (*LState, context.CancelFunc)
- func (ls *LState) NewTypeMetatable(typ string) *LTable
- func (ls *LState) NewUserData() *LUserData
- func (ls *LState) Next(tb *LTable, key LValue) (LValue, LValue)
- func (ls *LState) ObjLen(v1 LValue) int
- func (ls *LState) OpenLibs()
- func (ls *LState) OptBool(n int, d bool) bool
- func (ls *LState) OptChannel(n int, ch chan LValue) chan LValue
- func (ls *LState) OptFunction(n int, d *LFunction) *LFunction
- func (ls *LState) OptInt(n int, d int) int
- func (ls *LState) OptInt64(n int, d int64) int64
- func (ls *LState) OptNumber(n int, d LNumber) LNumber
- func (ls *LState) OptString(n int, d string) string
- func (ls *LState) OptTable(n int, d *LTable) *LTable
- func (ls *LState) OptUserData(n int, d *LUserData) *LUserData
- func (ls *LState) PCall(nargs, nret int, errfunc *LFunction) (err error)
- func (ls *LState) Pop(n int)
- func (ls *LState) PreloadModule(name string, loader LGFunction)
- func (ls *LState) Push(value LValue)
- func (ls *LState) RaiseError(format string, args ...interface{})
- func (ls *LState) RawEqual(lhs, rhs LValue) bool
- func (ls *LState) RawGet(tb *LTable, key LValue) LValue
- func (ls *LState) RawGetInt(tb *LTable, key int) LValue
- func (ls *LState) RawSet(tb *LTable, key LValue, value LValue)
- func (ls *LState) RawSetInt(tb *LTable, key int, value LValue)
- func (ls *LState) Register(name string, fn LGFunction)
- func (ls *LState) RegisterModule(name string, funcs map[string]LGFunction) LValue
- func (ls *LState) Remove(index int)
- func (ls *LState) RemoveCallerFrame() *callFrame
- func (ls *LState) RemoveContext() context.Context
- func (ls *LState) Replace(idx int, value LValue)
- func (ls *LState) Resume(th *LState, fn *LFunction, args ...LValue) (ResumeState, error, []LValue)
- func (ls *LState) SetContext(ctx context.Context)
- func (ls *LState) SetFEnv(obj LValue, env LValue)
- func (ls *LState) SetField(obj LValue, key string, value LValue)
- func (ls *LState) SetFuncs(tb *LTable, funcs map[string]LGFunction, upvalues ...LValue) *LTable
- func (ls *LState) SetGlobal(name string, value LValue)
- func (ls *LState) SetLocal(dbg *Debug, no int, lv LValue) string
- func (ls *LState) SetMetatable(obj LValue, mt LValue)
- func (ls *LState) SetMx(mx int)
- func (ls *LState) SetTable(obj LValue, key LValue, value LValue)
- func (ls *LState) SetTop(idx int)
- func (ls *LState) SetUpvalue(fn *LFunction, no int, lv LValue) string
- func (ls *LState) Status(th *LState) string
- func (ls *LState) String() string
- func (ls *LState) ToBool(n int) bool
- func (ls *LState) ToChannel(n int) chan LValue
- func (ls *LState) ToFunction(n int) *LFunction
- func (ls *LState) ToInt(n int) int
- func (ls *LState) ToInt64(n int) int64
- func (ls *LState) ToNumber(n int) LNumber
- func (ls *LState) ToString(n int) string
- func (ls *LState) ToStringMeta(lv LValue) LValue
- func (ls *LState) ToTable(n int) *LTable
- func (ls *LState) ToThread(n int) *LState
- func (ls *LState) ToUserData(n int) *LUserData
- func (ls *LState) Type() LValueType
- func (ls *LState) TypeError(n int, typ LValueType)
- func (ls *LState) Where(level int) string
- func (ls *LState) XMoveTo(other *LState, n int)
- func (ls *LState) Yield(values ...LValue) int
- type LString
- type LTable
- func (tb *LTable) Append(value LValue)
- func (tb *LTable) ForEach(cb func(LValue, LValue))
- func (tb *LTable) Insert(i int, value LValue)
- func (tb *LTable) Len() int
- func (tb *LTable) MaxN() int
- func (tb *LTable) Next(key LValue) (LValue, LValue)
- func (tb *LTable) RawGet(key LValue) LValue
- func (tb *LTable) RawGetH(key LValue) LValue
- func (tb *LTable) RawGetInt(key int) LValue
- func (tb *LTable) RawGetString(key string) LValue
- func (tb *LTable) RawSet(key LValue, value LValue)
- func (tb *LTable) RawSetH(key LValue, value LValue)
- func (tb *LTable) RawSetInt(key int, value LValue)
- func (tb *LTable) RawSetString(key string, value LValue)
- func (tb *LTable) Remove(pos int) LValue
- func (tb *LTable) String() string
- func (tb *LTable) Type() LValueType
- type LUserData
- type LValue
- type LValueType
- type Options
- type P
- type ResumeState
- type Upvalue
Constants ¶
const ( VarArgHasArg uint8 = 1 VarArgIsVarArg uint8 = 2 VarArgNeedsArg uint8 = 4 )
const ( // BaseLibName is here for consistency; the base functions have no namespace/library. BaseLibName = "" // LoadLibName is here for consistency; the loading system has no namespace/library. LoadLibName = "package" // TabLibName is the name of the table Library. TabLibName = "table" // IoLibName is the name of the io Library. IoLibName = "io" // OsLibName is the name of the os Library. OsLibName = "os" // StringLibName is the name of the string Library. StringLibName = "string" // MathLibName is the name of the math Library. MathLibName = "math" // DebugLibName is the name of the debug Library. DebugLibName = "debug" // ChannelLibName is the name of the channel Library. ChannelLibName = "channel" // CoroutineLibName is the name of the coroutine Library. CoroutineLibName = "coroutine" )
const ( OP_MOVE int = iota /* A B R(A) := R(B) */ OP_MOVEN /* A B R(A) := R(B); followed by R(C) MOVE ops */ OP_LOADK /* A Bx R(A) := Kst(Bx) */ OP_LOADBOOL /* A B C R(A) := (Bool)B; if (C) pc++ */ OP_LOADNIL /* A B R(A) := ... := R(B) := nil */ OP_GETUPVAL /* A B R(A) := UpValue[B] */ OP_GETGLOBAL /* A Bx R(A) := Gbl[Kst(Bx)] */ OP_GETTABLE /* A B C R(A) := R(B)[RK(C)] */ OP_GETTABLEKS /* A B C R(A) := R(B)[RK(C)] ; RK(C) is constant string */ OP_SETGLOBAL /* A Bx Gbl[Kst(Bx)] := R(A) */ OP_SETUPVAL /* A B UpValue[B] := R(A) */ OP_SETTABLE /* A B C R(A)[RK(B)] := RK(C) */ OP_SETTABLEKS /* A B C R(A)[RK(B)] := RK(C) ; RK(B) is constant string */ OP_NEWTABLE /* A B C R(A) := {} (size = BC) */ OP_SELF /* A B C R(A+1) := R(B); R(A) := R(B)[RK(C)] */ OP_ADD /* A B C R(A) := RK(B) + RK(C) */ OP_SUB /* A B C R(A) := RK(B) - RK(C) */ OP_MUL /* A B C R(A) := RK(B) * RK(C) */ OP_DIV /* A B C R(A) := RK(B) / RK(C) */ OP_MOD /* A B C R(A) := RK(B) % RK(C) */ OP_POW /* A B C R(A) := RK(B) ^ RK(C) */ OP_UNM /* A B R(A) := -R(B) */ OP_NOT /* A B R(A) := not R(B) */ OP_LEN /* A B R(A) := length of R(B) */ OP_CONCAT /* A B C R(A) := R(B).. ... ..R(C) */ OP_JMP /* sBx pc+=sBx */ OP_EQ /* A B C if ((RK(B) == RK(C)) ~= A) then pc++ */ OP_LT /* A B C if ((RK(B) < RK(C)) ~= A) then pc++ */ OP_LE /* A B C if ((RK(B) <= RK(C)) ~= A) then pc++ */ OP_TEST /* A C if not (R(A) <=> C) then pc++ */ OP_TESTSET /* A B C if (R(B) <=> C) then R(A) := R(B) else pc++ */ OP_CALL /* A B C R(A) ... R(A+C-2) := R(A)(R(A+1) ... R(A+B-1)) */ OP_TAILCALL /* A B C return R(A)(R(A+1) ... R(A+B-1)) */ OP_RETURN /* A B return R(A) ... R(A+B-2) (see note) */ OP_FORLOOP /* A sBx R(A)+=R(A+2); if R(A) <?= R(A+1) then { pc+=sBx; R(A+3)=R(A) }*/ OP_FORPREP /* A sBx R(A)-=R(A+2); pc+=sBx */ OP_TFORLOOP /* A C R(A+3) ... R(A+3+C) := R(A)(R(A+1) R(A+2)); if R(A+3) ~= nil then { pc++; R(A+2)=R(A+3); } */ OP_SETLIST /* A B C R(A)[(C-1)*FPF+i] := R(A+i) 1 <= i <= B */ OP_CLOSE /* A close all variables in the stack up to (>=) R(A)*/ OP_CLOSURE /* A Bx R(A) := closure(KPROTO[Bx] R(A) ... R(A+n)) */ OP_VARARG /* A B R(A) R(A+1) ... R(A+B-1) = vararg */ OP_NOP /* NOP */ )
const EnvironIndex = -10001
const FramesPerSegment = 8
FramesPerSegment should be a power of 2 constant for performance reasons. It will allow the go compiler to change the divs and mods into bitshifts. Max is 256 due to current use of uint8 to count how many frames in a segment are used.
const GlobalsIndex = -10002
const LNumberBit = 64
const LNumberScanFormat = "%f"
const LuaVersion = "Lua 5.1"
const MultRet = -1
const PackageAuthors = "Yusuke Inuzuka"
const PackageCopyRight = PackageName + " " + PackageVersion + " Copyright (C) 2015 -2017 " + PackageAuthors
const PackageName = "GopherLua"
const PackageVersion = "0.1"
const RegistryIndex = -10000
Variables ¶
var CallStackSize = 256
var CompatVarArg = true
var FieldsPerFlush = 50
var LFalse = LBool(false)
var LNil = LValue(&LNilType{})
var LTrue = LBool(true)
var LuaLDir string
var LuaOS string
var LuaPath = "LUA_PATH"
var LuaPathDefault string
var MaxArrayIndex = 67108864
var MaxTableGetLoop = 100
var RegistryGrowStep = 32
var RegistrySize = 256 * 20
Functions ¶
func LVAsString ¶
LVAsString returns string representation of a given LValue if the LValue is a string or number, otherwise an empty string.
func LVCanConvToString ¶
LVCanConvToString returns true if a given LValue is a string or number otherwise false.
func OpenChannel ¶
func OpenCoroutine ¶
func OpenPackage ¶
func OpenString ¶
func UpvalueIndex ¶
Types ¶
type ApiError ¶
type ApiError struct { Type ApiErrorType Object LValue StackTrace string // Underlying error. This attribute is set only if the Type is ApiErrorFile or ApiErrorSyntax Cause error }
type ApiErrorType ¶
type ApiErrorType int
const ( ApiErrorSyntax ApiErrorType = iota ApiErrorFile ApiErrorRun ApiErrorError ApiErrorPanic )
type CompileError ¶
func (*CompileError) Error ¶
func (e *CompileError) Error() string
type DbgLocalInfo ¶
type FunctionProto ¶
type FunctionProto struct { SourceName string LineDefined int LastLineDefined int NumUpvalues uint8 NumParameters uint8 IsVarArg uint8 NumUsedRegisters uint8 Code []uint32 Constants []LValue FunctionPrototypes []*FunctionProto DbgSourcePositions []int DbgLocals []*DbgLocalInfo DbgCalls []DbgCall DbgUpvalues []string // contains filtered or unexported fields }
func (*FunctionProto) String ¶
func (fp *FunctionProto) String() string
type LChannel ¶
type LChannel chan LValue
func (LChannel) Type ¶
func (ch LChannel) Type() LValueType
type LFunction ¶
type LFunction struct { IsG bool Env *LTable Proto *FunctionProto GFunction LGFunction Upvalues []*Upvalue }
func (*LFunction) Type ¶
func (fn *LFunction) Type() LValueType
type LGFunction ¶
type LNilType ¶
type LNilType struct{}
func (*LNilType) Type ¶
func (nl *LNilType) Type() LValueType
type LNumber ¶
type LNumber float64
func LVAsNumber ¶
LVAsNumber tries to convert a given LValue to a number.
func (LNumber) Type ¶
func (nm LNumber) Type() LValueType
type LState ¶
type LState struct { G *Global Parent *LState Env *LTable Panic func(*LState) Dead bool Options Options // contains filtered or unexported fields }
func (*LState) CheckChannel ¶
Checks whether the given index is an LChannel and returns this channel.
func (*LState) CheckFunction ¶
func (*LState) CheckInt64 ¶
func (*LState) CheckNumber ¶
func (*LState) CheckString ¶
func (*LState) CheckTable ¶
func (*LState) CheckThread ¶
func (*LState) CheckType ¶
func (ls *LState) CheckType(n int, typ LValueType)
func (*LState) CheckTypes ¶
func (ls *LState) CheckTypes(n int, typs ...LValueType)
func (*LState) CheckUserData ¶
func (*LState) Context ¶
Context returns the LState's context. To change the context, use WithContext.
func (*LState) CreateTable ¶
func (*LState) Error ¶
This function is equivalent to lua_error( http://www.lua.org/manual/5.1/manual.html#lua_error ).
func (*LState) GetMetatable ¶
func (*LState) GetTypeMetatable ¶
func (*LState) NewClosure ¶
func (ls *LState) NewClosure(fn LGFunction, upvalues ...LValue) *LFunction
func (*LState) NewFunction ¶
func (ls *LState) NewFunction(fn LGFunction) *LFunction
func (*LState) NewFunctionFromProto ¶
func (ls *LState) NewFunctionFromProto(proto *FunctionProto) *LFunction
func (*LState) NewThread ¶
func (ls *LState) NewThread() (*LState, context.CancelFunc)
NewThread returns a new LState that shares with the original state all global objects. If the original state has context.Context, the new state has a new child context of the original state and this function returns its cancel function.
func (*LState) NewTypeMetatable ¶
func (*LState) NewUserData ¶
func (*LState) OpenLibs ¶
func (ls *LState) OpenLibs()
OpenLibs loads the built-in libraries. It is equivalent to running OpenLoad, then OpenBase, then iterating over the other OpenXXX functions in any order.
func (*LState) OptChannel ¶
If the given index is a LChannel, returns this channel. If this argument is absent or is nil, returns ch. Otherwise, raises an error.
func (*LState) PreloadModule ¶
func (ls *LState) PreloadModule(name string, loader LGFunction)
Set a module loader to the package.preload table.
func (*LState) RaiseError ¶
This function is equivalent to luaL_error( http://www.lua.org/manual/5.1/manual.html#luaL_error ).
func (*LState) Register ¶
func (ls *LState) Register(name string, fn LGFunction)
func (*LState) RegisterModule ¶
func (ls *LState) RegisterModule(name string, funcs map[string]LGFunction) LValue
func (*LState) RemoveCallerFrame ¶
func (ls *LState) RemoveCallerFrame() *callFrame
RemoveCallerFrame removes the stack frame above the current stack frame. This is useful in tail calls. It returns the new current frame.
func (*LState) RemoveContext ¶
RemoveContext removes the context associated with this LState and returns this context.
func (*LState) SetContext ¶
SetContext set a context ctx to this LState. The provided ctx must be non-nil.
func (*LState) SetMetatable ¶
func (*LState) SetMx ¶
Set maximum memory size. This function can only be called from the main thread.
func (*LState) ToFunction ¶
func (*LState) ToStringMeta ¶
ToStringMeta returns string representation of given LValue. This method calls the `__tostring` meta method if defined.
func (*LState) ToUserData ¶
func (*LState) Type ¶
func (ls *LState) Type() LValueType
func (*LState) TypeError ¶
func (ls *LState) TypeError(n int, typ LValueType)
type LTable ¶
type LTable struct { Metatable LValue // contains filtered or unexported fields }
func (*LTable) ForEach ¶
ForEach iterates over this table of elements, yielding each in turn to a given function.
func (*LTable) Next ¶
This function is equivalent to lua_next ( http://www.lua.org/manual/5.1/manual.html#lua_next ).
func (*LTable) RawGet ¶
RawGet returns an LValue associated with a given key without __index metamethod.
func (*LTable) RawGetH ¶
RawGet returns an LValue associated with a given key without __index metamethod.
func (*LTable) RawGetInt ¶
RawGetInt returns an LValue at position `key` without __index metamethod.
func (*LTable) RawGetString ¶
RawGetString returns an LValue associated with a given key without __index metamethod.
func (*LTable) RawSet ¶
RawSet sets a given LValue to a given index without the __newindex metamethod. It is recommended to use `RawSetString` or `RawSetInt` for performance if you already know the given LValue is a string or number.
func (*LTable) RawSetH ¶
RawSetH sets a given LValue to a given index without the __newindex metamethod.
func (*LTable) RawSetInt ¶
RawSetInt sets a given LValue at a position `key` without the __newindex metamethod.
func (*LTable) RawSetString ¶
RawSetString sets a given LValue to a given string index without the __newindex metamethod.
func (*LTable) Type ¶
func (tb *LTable) Type() LValueType
type LValue ¶
type LValue interface { String() string Type() LValueType // contains filtered or unexported methods }
type LValueType ¶
type LValueType int
const ( LTNil LValueType = iota LTBool LTNumber LTString LTFunction LTUserData LTThread LTTable LTChannel )
func (LValueType) String ¶
func (vt LValueType) String() string
type Options ¶
type Options struct { // Call stack size. This defaults to `lua.CallStackSize`. CallStackSize int // Data stack size. This defaults to `lua.RegistrySize`. RegistrySize int // Allow the registry to grow from the registry size specified up to a value of RegistryMaxSize. A value of 0 // indicates no growth is permitted. The registry will not shrink again after any growth. RegistryMaxSize int // If growth is enabled, step up by an additional `RegistryGrowStep` each time to avoid having to resize too often. // This defaults to `lua.RegistryGrowStep` RegistryGrowStep int // Controls whether or not libraries are opened by default SkipOpenLibs bool // Tells whether a Go stacktrace should be included in a Lua stacktrace when panics occur. IncludeGoStackTrace bool // If `MinimizeStackMemory` is set, the call stack will be automatically grown or shrank up to a limit of // `CallStackSize` in order to minimize memory usage. This does incur a slight performance penalty. MinimizeStackMemory bool }
Options is a configuration that is used to create a new LState.
type ResumeState ¶
type ResumeState int
const ( ResumeOK ResumeState = iota ResumeYield ResumeError )