Luerl - an implementation of Lua in Erlang

Luerl is an implementation of Lua 5.2 written solely in pure Erlang.

Some things which are known not to be implemented or work properly:

label and goto
tail-call optimisation in return
only limited standard libraries
proper handling of __metatable
...

When to use Luerl

Fast Language Switch: Luerl should allow you to switch between Erlang and Lua incredibly fast, introducing a way to use very small bits of logic programmed in Lua, inside an Erlang application, with good performance.

Multicore: Luerl provides a way to transparently utilize multicores. The underlying Erlang VM takes care of the distribution.

Microprocesses: It should give you a Lua environment that allows you to effortlessly run tens of thousands of Lua processes in parallel, leveraging the famed microprocesses implementation of the Erlang VM. The empty Luerl State footprint will be yet smaller than the C Lua State footprint.

Forking Up: Because of the immutable nature of the Luerl VM, it becomes a natural operation to use the same Lua State as a starting point for multiple parallel calculations.

However, Luerl will generally run slower than a reasonable native Lua implementation. This is mainly due the emulation of mutable data on top of an immutable world. There is really no way around this. An alternative would be to implement a special Lua memory outside of the normal Erlang, but this would defeat the purpose of Luerl. It would instead be then more logical to connect to a native Lua.

Some valid use cases for Luerl are:

Lua code will be run only occasionally and it wouldn't be worth managing an extra language implementation in the application.
The Lua code chunks are small so the slower speed is weighed up by Luerl's faster interface.
The Lua code calculates and reads variables more than changing them.
The same Lua State is repeatedly used to 'fork up' as a basis for massively many parallel calculations, based on the same state.
It is easy to run multiple instances of Luerl which could better utilise multicores.

There may be others.

Interface functions in luerl.erl

All functions optionally accept a Lua State parameter. The Lua State is the state of a Lua VM instance. It can be carried from one call to the next. If no State is passed in, a new state is initiated for the function call.

Note that Forms (see definition below) can travel between different States. They are precompiled bits of code, independent of State. That you can 'carry them around' is unique to Luerl.

Please avoid directly accessing functions in other modules which haven't been defined here. There are no guarantees that they will not change.

eval and do functions differ only in what they return. The do functions return results and a new Lua State, the eval functions return a tuple starting on 'ok' or 'error', then the result, or cause of error.

do --> {Result, State} 

eval --> {ok, Result} | {error, Reason}

Spec Definitions:
Binary means an Erlang binary string.
Form means a portion of precompiled bytecode. (also ambiguously called Compiled Chunks here and Chunks in the samples.)
State means a Lua State, this is a Lua VM instance.
Path means a file system path and file name.
KeyPath means an Erlang list of atoms representing nested names, e.g. [table,pack] for table.pack.
Keys I don't know

Examples See below and files hello.erl and especially hello2.erl in examples/hello/.

####Note####

As it is possible in Lua to create self-referencing data structures, indeed the standard libraries have many instances of this, then using the functions which decode their return values can cause an infinite loop during the decoding. An simple example is the top level table which contains a key _G which references the top-level table.

luerl:eval(String|Binary|Form[, State]) -> {ok, Result} | {error, Reason}.

Evaluate a Lua expression passed in as a string or binary, and return its result.

luerl:evalfile(Path[, State]) -> {ok, Result} | {error, Reason}.

Load and execute a file, and return the result.

luerl:do(String|Binary|Form[, State]) -> {Result, NewState}.

Evaluate a Lua expression and return its result, and the new Lua State.

luerl:dofile(Path[, State]) -> {Result, NewState}.

Load and execute the Lua code in the file and return its result, and the new Lua State. Equivalent to doing luerl:do("return dofile('FileName')").

luerl:load(String|Binary[, State]) -> {ok,Function,NewState} | {error, Reason} .

Parse a Lua chunk as string or binary, and return a compiled chunk ('form').

luerl:loadfile(FileName[, State]) -> {ok,Function,NewState}.

Parse a Lua file, and return a compiled chunk ('form').

luerl:path_loadfile([Path, ], FileName, State) -> {ok,Function,FullName,State}.

Search Path until the file FileName is found. Parse the file and return a compiled chunk ('form'). If Path is not given then the path defined in the environment variable LUA_LOAD_PATH is used.

luerl:load_module(KeyPath, ErlangModule, State) -> State.

Load ErlangModule and install its table at KeyPath.

luerl:load_module1(KeyPath, ErlangModule, State) -> State.

Load ErlangModule and install its table at KeyPath.

luerl:init() -> State.

Get a new Lua State = a fresh Lua VM instance.

luerl:call(Form, Args[, State]) -> {Result,State}

luerl:call_chunk(Form, Args[, State]) -> {Result,State}

Call a compiled chunk or function. Use the call_chunk, call has been kept for backwards compatibility.

luerl:call_function(KeyPath, Args[, State]) -> {Result,NewState}

Call a function already defined in the state. KeyPath is a list of names to the function. KeyPath, Args and Result are automatically encode/decoded.

luerl:call_function1(KeyPath, Args, State) -> {Result,NewState}

Call a function already defined in the state. KeyPath is a list of keys to the function. KeyPath, Args and Result are NOT encode/decoded.

luerl:call_method(MethPath, Args[, State]) -> {Result,NewState}.

Call a method already defined in the state. MethPath is a list of names to the method. MethPath, Args and Result are automatically encode/decoded.

luerl:call_method1(MethPath, Args, State) -> {Result,NewState}

Call a method already defined in the state. MethPath is a list of keys to the method. Keys, Args and Result are NOT encode/decoded.

luerl:stop(State) -> GCedState.

Garbage collects the state and (todo:) does away with it.

luerl:gc(State) -> State.

Runs the (experimental) garbage collector on a state and returns the new state.

luerl:set_table(Path, Value, State) -> State.

Sets a value inside the Lua state. Value is automatically encoded.

You can use this function to expose an function to the Lua code by using this interface: fun(Args, State) -> {Results, State} Args and Results must be a list of Luerl compatible erlang values.

N.B. This interface is subject to change!

Included Examples

To run the examples, do make and then start the Erlang command line with erl -pa ./ebin.
Don't be shocked by the very long dump following each function call.
At the command line you are seeing the Lua State dumped, that is returned by these calls:

execute a string

luerl:do("print(\"Hello, Robert(o)!\")").

execute a file

luerl:dofile("./examples/hello/hello.lua").

separately parse, then execute

EmptyState = luerl:init(),
{ok, Chunk, State} = luerl:load("print(\"Hello, Chunk!\")", EmptyState),
{_Ret, _NewState} = luerl:do(Chunk, State).

call a function in the state

{Res,State1} = luerl:call_function([table,pack], [<<"a">>,<<"b">>,42], State0)

executes the call table.pack("a", "b", 42) in State0. E.g.:

{Res,State1} = luerl:call([table,pack], [<<"a">>,<<"b">>,42]),
io:format("~p~n",[Res]).

call a method in the state

{Res,State1} = luerl:call_method([g,h,i], [<<"a">>,<<"b">>,42], State0)

executes the call g.h:i("a", "b", 42) in State0.

define a method in the state

State1 = luerl:set_table([inc], fun([Val], State) -> {[Val+1], State} end)

the method can be called like this:

luerl:do(<<"print(inc(4))">>, State1)

For more examples see examples/hello/hello2.erl.

Examples

For more exhaustive examples see examples/hello/hello2.erl:

./hello.erl is a very brief example while examples/hello/hello2.erl is a comprehensive lists of most ways that come to mind of how to use the individual interface functions.

You can build and run these samples with:

make examples

Library Module

There is also a library module, luerl_lib, which contains functions which may be used.

luerl_lib:first_value(ReturnList) -> Value.

luerl_lib:is_true_value(ReturnList) -> true | false.

Currently implemented functions in the libraries

_G
_VERSION
assert
collectgarbage
dofile
eprint
error
getmetatable
ipairs
load
loadfile
next
pairs
pcall
print
rawequal
rawget
rawlen
rawset
require
select
setmetatable
tonumber
tostring
type
unpack
io.flush
io.write
math.abs
math.acos
math.asin
math.atan
math.atan2
math.ceil
math.cos
math.cosh
math.deg
math.exp
math.floor
math.fmod
math.frexp
math.huge
math.ldexp
math.log
math.log10
math.max
math.min
math.modf
math.pi
math.pow
math.rad
math.random
math.randomseed
math.sin
math.sinh
math.sqrt
math.tan
math.tanh
os.clock
os.date
os.difftime
os.getenv
os.time
package.config
package.loaded
package.preload
package.path
package.searchers
package.searchpath
string.byte
string.char
string.find
string.format (should handle most things now)
string.gmatch
string.gsub
string.len
string.lower
string.match
string.rep
string.reverse
string.sub
string.upper
table.concat
table.insert
table.pack
table.remove
table.sort
table.unpack
bit32.band
bit32.bnot
bit32.bor
bit32.btest
bit32.bxor
bit32.lshift
bit32.rshift
bit32.arshift
bit32.lrotate
bit32.rrotate
bit32.extract
bit32.replace
debug.getmetatable
debug.getuservalue
debug.setmetatable
debug.setuservalue

Known Bugs

Functions defined in a loop, while, repeat and for, and when the loop is exited with a break from inside an if will generate an error when called. For example the functions defined in

for i=1,10 do
  a[i] = {set = function(x) i=x end, get = function () return i end}
  if i == 3 then break end
end

N.B. This only occurs if the loop is actually exited with the break, otherwise there is no problem.

bycanvas/luerl