luerl (luerl v1.5.0)

View Source

Luerl is an implementation of Lua 5.3 written in Erlang. This is the main public API module for interfacing with Luerl.

The LuaState parameter is the state of a Lua VM instance. It must be created with the init/0 call and be threaded from one call to the next.

Note that Luerl, following Lua, does do any implicit UTF-8 encoding of input strings. This means that all strings given as arguments to the calls or the strings to evaluate with do/3 or do_dec/3 need to have already been UTF-8 encoded. This can be quite easily do with the ~ or ~b sigils. For example

luerl:do(~b"return 'árvíztűrő tükörfúrógép'", St0)

or

luerl:do(~"return 'árvíztűrő tükörfúrógép'", St0)

Summary

Types

luerldata()
luerlstate()

Functions

externalize(LuaState)
gc(LuaState)

Runs the garbage collector on a state and returns the new state.

get_stacktrace(LuaState)

Return a stack trace of the current call stack in the state.

init()

Create a new Lua state which is a fresh Lua VM instance.

internalize(LuaState)

Encode/Decode Data functions

decode(LuerlTerm, LuaState)

Decode a Luerl term into its standard Erlang representation. Note that we have to detect recursive references and generate an error when this occurs.

decode_list(LuerlTerms, LuaState)

Decode a list of Luerl terms into their standard Erlang representation. Note that we have to detect recursive references and generate an error when this occurs.

encode(Term, LuaState)

Encode an Erlang term into its Luerl representation if possible.

encode_list(Terms, LuaState)

Encode a list of Erlang terms into their Luerl representations if possible.

Evaluate Code functions

do(Expression, LuaState)

Equivalent to do(Expression, [return], LuaState).

do(Expression, CompileOptions, LuaState)

Compile a Lua expression string, evaluate it and return its result, which is NOT decoded, and the new Lua State.

do_dec(Expression, LuaState)

Equivalent to do_dec(Expression, [return], LuaState).

do_dec(Expression, CompileOptions, LuaState)

Compile a Lua expression string, evaluate it and return its result, which is is decoded, and the new Lua State.

dofile(FileName, LuaState)

Equivalent to dofile(FileName, [return], LuaState).

dofile(FileName, CompileOptions, LuaState)

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

dofile_dec(FileName, LuaState)

Equivalent to dofile_dec(FileName, [return], LuaState).

dofile_dec(FileName, CompileOptions, LuaState)

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

Function/Method Call functions

call(LuaFuncRef, Args, LuaState)

Equivalent to call_function(LuaFuncRef, Args, LuaState).

call_chunk(LuaFuncRef, LuaState)

Equivalent to call_function(LuaFuncRef, [], LuaState).

call_chunk(LuaFuncRef, Args, LuaState)

Equivalent to call_function(LuaFuncRef, Args, LuaState).

call_function(LuaFuncRef, Args, LuaState)

Call a function already defined in the state. LuaFuncReaf and Args are NOT automatically encoded and Result is NOT automatically decoded.

call_function_dec(KeyPath, Args, LuaState)

Call a function already defined in the state. KeyPath is a list of keys to the function. KeyPath and Args are automatically encoded, while Result is automatically decoded.

call_function_enc(KeyPath, Args, LuaState)

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

call_method(LuaTable, Method, Args, LuaState)

Call the Method in the LuaTable with the Args. The LuaTable, Method and Args are NOT automatically encoded and the Result is NOT automatically decoded

call_method_dec(KeyPath, Method, Args, LuaState)

Call the Method in the Table with the Args. The Table, Method and Args are automatically encoded and the Result is automatically decoded.

Load Code functions

load(LuaCode, LuaState)

Equivalent to load(LuaChunk, [return], LuaState).

load(LuaCode, CompileOptions, LuaState)

Parse Lua chunk code as string or binary, and return a compiled chunk function.

load_module(KeyPath, ErlangModule, LuaState)

Load ErlangModule and install its table at KeyPath in the LuaTable which is NOT automatically Lua encoded.

load_module_dec(KeyPath, ErlangModule, LuaState)

Load ErlangModule and install its table at KeyPath in the LuaTable which is automatically Lua encoded.

loadfile(FileName, LuaState)

Equivalent to loadfile(FileName, [return], LuaState).

loadfile(FileName, CompileOptions, LuaState)

Parse a Lua file, and return a compiled chunk function.

path_loadfile(FileName, LuaState)

Calls path_loadfile/4 with Path set the value of LUA_LOAD_PATH and CompileOptions set to [return].

path_loadfile(Path, FileName, LuaState)

Equivalent to path_loadfile(Path, FileName, [return], LuaState).

path_loadfile(Path, FileName, CompileOptions, LuaState)

Search down a Path to find the Lua file and return a compiled ('form').

Lua Table Access functions

get_table_key(Table, Key, LuaState)

Get the value of a key in a table. Table, Key are NOT encoded and the Result is NOT decoded.

get_table_keys(KeyPath, LuaState)

Gets a value inside the Lua state. KeyPath is NOT encoded and Result is NOT decoded.

get_table_keys_dec(KeyPath, LuaState)

Gets a value inside the Lua state. KeyPath is automatically encoded and Result is automatically decoded.

set_table_key(Table, Key, Value, LuaState)

Set the value of a key in a table. Table, Key and Value are NOT encoded.

set_table_keys(KeyPath, Value, LuaState)

Sets a value inside the Lua state. KeyPath and Value are NOT encoded.

set_table_keys_dec(KeyPath, Value, LuaState)

Sets a value inside the Lua state. KeyPath and Value are automatically encoded.

Private Data functions

delete_private(Key, LuaState)

Delete the private value for Key.

get_private(Key, LuaState)

Get the private value for Key.

put_private(Key, Value, LuaState)

Puts a private Value under Key that is not exposed to the runtime.

Trace Control functions

clear_trace_func(LuaState)

Clear the trace function.

get_trace_data(LuaState)

Get the current trace data.

set_trace_data(TraceData, LuaState)

Set the trace data.

set_trace_func(Function, LuaState)

Set the trace function.

Types

luerldata()

-type luerldata() ::
          nil |
          boolean() |
          binary() |
          number() |
          #tref{i :: term()} |
          #usdref{i :: term()} |
          #eref{i :: term()} |
          #funref{i :: term(), env :: term()} |
          #erl_func{code :: term()} |
          #erl_mfa{m :: term(), f :: term(), a :: term()}.

luerlstate()

-type luerlstate() ::
          #luerl{tabs :: term(),
                 envs :: term(),
                 usds :: term(),
                 fncs :: term(),
                 g :: term(),
                 stk :: term(),
                 cs :: term(),
                 meta :: term(),
                 rand :: term(),
                 tag :: term(),
                 trace_func :: term(),
                 trace_data :: term(),
                 private :: term()}.

Functions

externalize(LuaState)

-spec externalize(LuaState) -> LuaState when LuaState :: luerlstate().

gc(LuaState)

-spec gc(LuaState) -> LuaState when LuaState :: luerlstate().

Runs the garbage collector on a state and returns the new state.

get_stacktrace(LuaState)

-spec get_stacktrace(LuaState) -> [FuncCall]
                        when
                            LuaState :: luerlstate(),
                            FuncCall :: {FuncName, CallArgs, ExtraInfo},
                            FuncName :: atom(),
                            ExtraInfo :: [{atom(), term()}],
                            CallArgs :: [term()].

Return a stack trace of the current call stack in the state.

init()

-spec init() -> LuaState when LuaState :: luerlstate().

Create a new Lua state which is a fresh Lua VM instance.

internalize(LuaState)

-spec internalize(LuaState) -> LuaState when LuaState :: luerlstate().

Encode/Decode Data functions

decode(LuerlTerm, LuaState)

-spec decode(LuerlTerm, LuaState) -> Term
                when LuerlTerm :: luerldata(), Term :: term(), LuaState :: luerlstate().

Decode a Luerl term into its standard Erlang representation. Note that we have to detect recursive references and generate an error when this occurs.

decode_list(LuerlTerms, LuaState)

-spec decode_list([LuerlTerm], LuaState) -> [Term]
                     when LuerlTerm :: luerldata(), Term :: term(), LuaState :: luerlstate().

Decode a list of Luerl terms into their standard Erlang representation. Note that we have to detect recursive references and generate an error when this occurs.

encode(Term, LuaState)

-spec encode(Term, LuaState) -> {LuerlTerm, LuaState}
                when LuerlTerm :: luerldata(), Term :: term(), LuaState :: luerlstate().

Encode an Erlang term into its Luerl representation if possible.

encode_list(Terms, LuaState)

-spec encode_list([Term], LuaState) -> {[LuerlTerm], LuaState}
                     when LuerlTerm :: term(), Term :: term(), LuaState :: luerlstate().

Encode a list of Erlang terms into their Luerl representations if possible.

Evaluate Code functions

do(Expression, LuaState)

-spec do(Expression, LuaState) -> {ok, Result, LuaState} | LuaError | CompileError
            when
                Expression :: string(),
                LuaState :: luerlstate(),
                Result :: [luerldata()],
                LuaError :: {lua_error, term(), LuaState},
                CompileError :: {error, [term()], [term()]}.

Equivalent to do(Expression, [return], LuaState).

do(Expression, CompileOptions, LuaState)

-spec do(Expression, CompileOptions, LuaState) -> {ok, Result, LuaState} | LuaError | CompileError
            when
                Expression :: string(),
                CompileOptions :: [term()],
                LuaState :: luerlstate(),
                Result :: [luerldata()],
                LuaError :: {lua_error, term(), LuaState},
                CompileError :: {error, [term()], [term()]}.

Compile a Lua expression string, evaluate it and return its result, which is NOT decoded, and the new Lua State.

do_dec(Expression, LuaState)

-spec do_dec(Expression, LuaState) -> {ok, Result, LuaState} | LuaError | CompileError
                when
                    Expression :: string(),
                    Result :: [term()],
                    LuaState :: luerlstate(),
                    LuaError :: {lua_error, term(), LuaState},
                    CompileError :: {error, [term()], [term()]}.

Equivalent to do_dec(Expression, [return], LuaState).

do_dec(Expression, CompileOptions, LuaState)

-spec do_dec(Expression, CompileOptions, LuaState) -> {ok, Result, LuaState} | LuaError | CompileError
                when
                    Expression :: string(),
                    CompileOptions :: [term()],
                    LuaState :: luerlstate(),
                    Result :: [term()],
                    LuaError :: {lua_error, term(), LuaState},
                    CompileError :: {error, [term()], [term()]}.

Compile a Lua expression string, evaluate it and return its result, which is is decoded, and the new Lua State.

dofile(FileName, LuaState)

-spec dofile(FileName, LuaState) -> {ok, Result, LuaState} | LuaError | CompileError
                when
                    FileName :: string(),
                    LuaState :: luerlstate(),
                    Result :: [luerldata()],
                    LuaError :: {lua_error, term(), LuaState},
                    CompileError :: {error, [term()], [term()]}.

Equivalent to dofile(FileName, [return], LuaState).

dofile(FileName, CompileOptions, LuaState)

-spec dofile(FileName, CompileOptions, LuaState) -> {ok, Result, LuaState} | LuaError | CompileError
                when
                    FileName :: string(),
                    CompileOptions :: [term()],
                    LuaState :: luerlstate(),
                    Result :: [luerldata()],
                    LuaError :: {lua_error, term(), LuaState},
                    CompileError :: {error, [term()], [term()]}.

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

dofile_dec(FileName, LuaState)

-spec dofile_dec(FileName, LuaState) -> {ok, Result, LuaState} | LuaError | CompileError
                    when
                        FileName :: string(),
                        Result :: [term()],
                        LuaState :: luerlstate(),
                        LuaError :: {lua_error, term(), LuaState},
                        CompileError :: {error, [term()], [term()]}.

Equivalent to dofile_dec(FileName, [return], LuaState).

dofile_dec(FileName, CompileOptions, LuaState)

-spec dofile_dec(FileName, CompileOptions, LuaState) -> {ok, Result, LuaState} | LuaError | CompileError
                    when
                        FileName :: string(),
                        CompileOptions :: [term()],
                        LuaState :: luerlstate(),
                        Result :: [luerldata()],
                        LuaError :: {lua_error, term(), LuaState},
                        CompileError :: {error, [term()], [term()]}.

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

Function/Method Call functions

call(LuaFuncRef, Args, LuaState)

Equivalent to call_function(LuaFuncRef, Args, LuaState).

call_chunk(LuaFuncRef, LuaState)

Equivalent to call_function(LuaFuncRef, [], LuaState).

call_chunk(LuaFuncRef, Args, LuaState)

Equivalent to call_function(LuaFuncRef, Args, LuaState).

call_function(LuaFuncRef, Args, LuaState)

-spec call_function(LuaFuncRef, Args, LuaState) -> {ok, Result, LuaState} | LuaError
                       when
                           LuaFuncRef :: [luerldata()] | luerldata(),
                           Args :: [luerldata()],
                           LuaState :: luerlstate(),
                           Result :: [luerldata()],
                           LuaError :: {lua_error, term(), LuaState}.

Call a function already defined in the state. LuaFuncReaf and Args are NOT automatically encoded and Result is NOT automatically decoded.

call_function_dec(KeyPath, Args, LuaState)

-spec call_function_dec(KeyPath, Args, LuaState) -> {ok, Result, LuaState} | LuaError
                           when
                               KeyPath :: [term()],
                               Args :: [term()],
                               LuaState :: luerlstate(),
                               Result :: [term()],
                               LuaError :: {lua_error, term(), LuaState}.

Call a function already defined in the state. KeyPath is a list of keys to the function. KeyPath and Args are automatically encoded, while Result is automatically decoded.

call_function_enc(KeyPath, Args, LuaState)

-spec call_function_enc(KeyPath, Args, LuaState) -> {ok, Result, LuaState} | LuaError
                           when
                               KeyPath :: [term()],
                               Args :: [term()],
                               LuaState :: luerlstate(),
                               Result :: [luerldata()],
                               LuaError :: {lua_error, term(), LuaState}.

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

call_method(LuaTable, Method, Args, LuaState)

-spec call_method(LuaTable, Method, Args, LuaState) -> {ok, Result, LuaState} | LuaError
                     when
                         LuaTable :: #tref{i :: term()},
                         Method :: luerldata(),
                         Args :: [luerldata()],
                         LuaState :: luerlstate(),
                         Result :: [luerldata()],
                         LuaError :: {lua_error, term(), LuaState}.

Call the Method in the LuaTable with the Args. The LuaTable, Method and Args are NOT automatically encoded and the Result is NOT automatically decoded

call_method_dec(KeyPath, Method, Args, LuaState)

-spec call_method_dec(KeyPath, Method, Args, LuaState) -> {ok, Result, LuaState} | LuaError
                         when
                             KeyPath :: [term()],
                             Method :: term(),
                             Args :: [term()],
                             LuaState :: luerlstate(),
                             Result :: [term()],
                             LuaError :: {lua_error, term(), LuaState}.

Call the Method in the Table with the Args. The Table, Method and Args are automatically encoded and the Result is automatically decoded.

Load Code functions

load(LuaCode, LuaState)

-spec load(LuaCode, LuaState) -> {ok, Function, LuaState} | CompileError
              when
                  LuaCode :: binary() | string(),
                  Function :: #funref{i :: term(), env :: term()},
                  LuaState :: luerlstate(),
                  CompileError :: {error, [term()], [term()]}.

Equivalent to load(LuaChunk, [return], LuaState).

load(LuaCode, CompileOptions, LuaState)

-spec load(LuaCode, CompileOptions, LuaState) -> {ok, Function, LuaState} | CompileError
              when
                  LuaCode :: binary() | string(),
                  CompileOptions :: [term()],
                  LuaState :: luerlstate(),
                  Function :: #funref{i :: term(), env :: term()},
                  CompileError :: {error, [term()], [term()]}.

Parse Lua chunk code as string or binary, and return a compiled chunk function.

load_module(KeyPath, ErlangModule, LuaState)

-spec load_module(KeyPath, ErlangModule, LuaState) -> LuaState
                     when KeyPath :: [luerldata()], ErlangModule :: atom(), LuaState :: luerlstate().

Load ErlangModule and install its table at KeyPath in the LuaTable which is NOT automatically Lua encoded.

load_module_dec(KeyPath, ErlangModule, LuaState)

-spec load_module_dec(KeyPath, ErlangModule, LuaState) -> LuaState
                         when KeyPath :: [term()], ErlangModule :: atom(), LuaState :: luerlstate().

Load ErlangModule and install its table at KeyPath in the LuaTable which is automatically Lua encoded.

loadfile(FileName, LuaState)

-spec loadfile(FileName, LuaState) -> {ok, Function, LuaState} | CompileError
                  when
                      FileName :: string(),
                      LuaState :: luerlstate(),
                      Function :: #funref{i :: term(), env :: term()},
                      CompileError :: {error, [term()], [term()]}.

Equivalent to loadfile(FileName, [return], LuaState).

loadfile(FileName, CompileOptions, LuaState)

-spec loadfile(FileName, CompileOptions, LuaState) -> {ok, Function, LuaState} | CompileError
                  when
                      FileName :: string(),
                      CompileOptions :: [term()],
                      LuaState :: luerlstate(),
                      Function :: #funref{i :: term(), env :: term()},
                      CompileError :: {error, [term()], [term()]}.

Parse a Lua file, and return a compiled chunk function.

path_loadfile(FileName, LuaState)

-spec path_loadfile(FileName, LuaState) -> {ok, Function, FullName, LuaState} | CompileError
                       when
                           FileName :: string(),
                           LuaState :: luerlstate(),
                           Function :: #funref{i :: term(), env :: term()},
                           FullName :: string(),
                           CompileError :: {error, [term()], term()}.

Calls path_loadfile/4 with Path set the value of LUA_LOAD_PATH and CompileOptions set to [return].

path_loadfile(Path, FileName, LuaState)

-spec path_loadfile(Path, FileName, LuaState) -> {ok, Function, FullName, LuaState} | CompileError
                       when
                           Path :: [string()],
                           FileName :: string(),
                           LuaState :: luerlstate(),
                           Function :: #funref{i :: term(), env :: term()},
                           FullName :: string(),
                           CompileError :: {error, [term()], [term()]}.

Equivalent to path_loadfile(Path, FileName, [return], LuaState).

path_loadfile(Path, FileName, CompileOptions, LuaState)

-spec path_loadfile(Path, FileName, CompileOptions, LuaState) ->
                       {ok, Function, FullName, LuaState} | CompileError
                       when
                           Path :: [string()],
                           FileName :: string(),
                           FullName :: string(),
                           CompileOptions :: [term()],
                           LuaState :: luerlstate(),
                           Function :: #funref{i :: term(), env :: term()},
                           CompileError :: {error, [term()], [term()]}.

Search down a Path to find the Lua file and return a compiled ('form').

Lua Table Access functions

get_table_key(Table, Key, LuaState)

-spec get_table_key(Table, Key, LuaState) -> {ok, Result, LuaState} | LuaError
                       when
                           Table :: luerldata(),
                           Key :: luerldata(),
                           LuaState :: luerlstate(),
                           Result :: luerldata(),
                           LuaError :: {lua_error, term(), LuaState}.

Get the value of a key in a table. Table, Key are NOT encoded and the Result is NOT decoded.

get_table_keys(KeyPath, LuaState)

-spec get_table_keys(KeyPath, LuaState) -> {ok, Result, LuaState} | LuaError
                        when
                            KeyPath :: [luerldata()],
                            LuaState :: luerlstate(),
                            Result :: luerldata(),
                            LuaError :: {lua_error, term(), LuaState}.

Gets a value inside the Lua state. KeyPath is NOT encoded and Result is NOT decoded.

get_table_keys_dec(KeyPath, LuaState)

-spec get_table_keys_dec(KeyPath, LuaState) -> {ok, Result, LuaState} | LuaError
                            when
                                KeyPath :: [term()],
                                LuaState :: luerlstate(),
                                Result :: term(),
                                LuaError :: {lua_error, term(), LuaState}.

Gets a value inside the Lua state. KeyPath is automatically encoded and Result is automatically decoded.

set_table_key(Table, Key, Value, LuaState)

-spec set_table_key(Table, Key, Value, LuaState) -> {ok, LuaState} | LuaError
                       when
                           Table :: luerldata(),
                           Key :: luerldata(),
                           Value :: luerldata(),
                           LuaState :: luerlstate(),
                           LuaError :: {lua_error, term(), LuaState}.

Set the value of a key in a table. Table, Key and Value are NOT encoded.

set_table_keys(KeyPath, Value, LuaState)

-spec set_table_keys(KeyPath, Value, LuaState) -> {ok, LuaState} | LuaError
                        when
                            KeyPath :: [luerldata()],
                            Value :: luerldata(),
                            LuaState :: luerlstate(),
                            LuaError :: {lua_error, term(), LuaState}.

Sets a value inside the Lua state. KeyPath and Value are NOT encoded.

set_table_keys_dec(KeyPath, Value, LuaState)

-spec set_table_keys_dec(KeyPath, Value, LuaState) -> {ok, LuaState} | LuaError
                            when
                                KeyPath :: [term()],
                                Value :: term(),
                                LuaState :: luerlstate(),
                                LuaError :: {lua_error, term(), LuaState}.

Sets a value inside the Lua state. KeyPath and Value are automatically encoded.

Private Data functions

delete_private(Key, LuaState)

-spec delete_private(Key, LuaState) -> LuaState when Key :: term(), LuaState :: luerlstate().

Delete the private value for Key.

get_private(Key, LuaState)

-spec get_private(Key, LuaState) -> Value when Key :: term(), Value :: term(), LuaState :: luerlstate().

Get the private value for Key.

put_private(Key, Value, LuaState)

-spec put_private(Key, Value, LuaState) -> LuaState
                     when Key :: term(), Value :: term(), LuaState :: luerlstate().

Puts a private Value under Key that is not exposed to the runtime.

Trace Control functions

clear_trace_func(LuaState)

-spec clear_trace_func(LuaState) -> LuaState when LuaState :: luerlstate().

Clear the trace function.

get_trace_data(LuaState)

-spec get_trace_data(LuaState) -> TraceData when LuaState :: luerlstate(), TraceData :: term().

Get the current trace data.

set_trace_data(TraceData, LuaState)

-spec set_trace_data(TraceData, LuaState) -> LuaState when LuaState :: luerlstate(), TraceData :: term().

Set the trace data.

set_trace_func(Function, LuaState)

-spec set_trace_func(Function, LuaState) -> LuaState when Function :: fun(), LuaState :: luerlstate().

Set the trace function.