Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Force explicit encoding/decoding of arguments and return values to calls to Erlang #194

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from
Open

Force explicit encoding/decoding of arguments and return values to calls to Erlang #194

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bede967
Encoded/decoded functions explicit encoding/decoding of arguments
rvirding Oct 28, 2024
d148483
Check if calling #erl_func and #erl_mfa return a list
rvirding Oct 28, 2024
0f3f273
First complete test version of new luerl
rvirding Nov 12, 2024
7f1c5f4
Fix the Elixir interface modules for luerl and luerl_old
rvirding Nov 12, 2024
4e74109
Fix tests on develop-encode
davydog187 Nov 30, 2024
23fff36
Merge pull request #196 from rvirding/fix-tests
davydog187 Nov 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 116 additions & 86 deletions doc/luerl.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,137 +1,167 @@
luerl(3) luerl(3)
luerl(3) Library Functions Manual luerl(3)

Name
luerl - The basic interface to the Luerl system


Interface functions
Interface functions - New Version
The Lua State parameter is the state of a Lua VM instance. It must be
created with the luerl:init() call and be carried from one call to the
next.

As it is possible in Lua to create self‐referencing data structures,
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 will generate an error
when they would 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.
the top-level table.

Note that Lua Chunks (see definition below) can travel between differ‐
ent States. They are precompiled bits of code, independent of State.
That you can ‘carry around’ this is no unique to Luerl but a low‐level
implementation detail of the standard Lua language (https://lua.org),
for more on chunks read (https://www.lua.org/manual/5.3/manu‐
al.html#3.3.2) the official Lua 5.3 reference manual
(https://www.lua.org/manual/5.3/manual.html).
Note that Lua Chunks (see definition below) can travel between differ‐
ent States. They are precompiled bits of code, independent of State.
That you can ‘carry around’ this is no unique to Luerl but a low-level
implementation detail of the standard Lua language ⟨https://lua.org⟩,
for more on chunks read ⟨https://www.lua.org/manual/5.3/man‐
ual.html#3.3.2⟩ the official Lua 5.3 reference manual
⟨https://www.lua.org/manual/5.3/manual.html⟩.

Spec Definitions
Binary means an Erlang binary string.
Chunks means a portion of precompiled bytecode.
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,
KeyPath means an Erlang list of atoms representing nested names,
e.g. [table,pack] for table.pack.
Keys means Lua table keys, the keys of a key‐value structure.

Functions
eval and do functions differ only in what they return. The do func‐
tions 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}
Keys means Lua table keys, the keys of a key-value structure.

luerl:eval(String|Binary|Form, State) ‐> {ok, Result} | {error, Reason,
StackTrace}.
Evaluate a Lua expression passed in as a string or binary, and return
its result.
CompileOptions means a list of compiler options. Currently supported
options are ‘return’, which returns the errors and warnings, and ‘re‐
port’ which will log the errors and warnings.

luerl:evalfile(Path, State) ‐> {ok, Result} | {error, Reason, StackTrace}.
Load and execute a file, and return the result.
LuaCallReturn = {ok, Result, State} | {lua_error, Error, State}
This is the return value from evaluating a Lua call.

luerl:do(String|Binary|Form, State) ‐> {Result, NewState}.
Evaluate a Lua expression and return its result, and the new Lua State.
Functions
luerl:init() -> State
Get a new Lua State = a fresh Lua VM instance.

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(‘File‐
Name’)”).
luerl:gc(State) -> State
Runs the garbage collector on a state and returns the new state.

luerl:load(String|Binary[, CompileOptions], State) ‐> {ok,Function,New‐
State} | {error, Reason}.
Parse a Lua chunk as string or binary, and return a compiled chunk
luerl:load(String|Binary[, CompileOptions], State) -> {ok, Function, State}
| CompileError
Parse a Lua chunk as string or binary, and return a compiled chunk
(‘form’).

luerl:loadfile(FileName[, CompileOptions], State) ‐> {ok,Function,NewState}
| {error, Reason}.
luerl:loadfile(FileName[, CompileOptions], State) -> {ok, Function, State}
| CompileError
Parse a Lua file, and return a compiled chunk (‘form’).

luerl:path_loadfile([Path, ], FileName[, CompileOptions], State) ‐>
{ok,Function,FullName,State} | {error, Reason}.
Search Path until the file FileName is found. Parse the file and re‐
luerl:path_loadfile([Path, ], FileName[, CompileOptions], State) ->
{ok,Function,FullName,State} | {error, Reason}
Search Path until the file FileName is found. Parse the file and re‐
turn a compiled chunk (‘form’). If Path is not given then the path de‐
fined in the environment variable LUA_LOAD_PATH is used.

luerl:load_module(KeyPath, ErlangModule, State) ‐> State.
Load ErlangModule and install its table at KeyPath which is encoded.

luerl:load_module1(KeyPath, ErlangModule, State) ‐> State.
Load ErlangModule and install its table at KeyPath which is NOT encoded
luerl:load_module(KeyPath, ErlangModule, State) -> State
Load ErlangModule and install its table at KeyPath which is NOT en‐
coded.

luerl:init() ‐> State.
Get a new Lua State = a fresh Lua VM instance.
luerl:load_module_dec(EncodedKeyPath, ErlangModule, State) -> State
Load ErlangModule and install its table at KeyPath which is encoded.

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
luerl:do(String|Binary|Form, State) -> {ok, Result, NewState} | {lua_error,
Error, State} | CompileError
Evaluate a Lua expression and return its result which is NOT decoded,
and the new Lua State.

luerl:do_dec(String|Binary|Form, State) -> {ok, Result, NewState} |
{lua_error, Error, State} | CompileError
Evaluate a Lua expression and return its result which is automatically
decoded, and the new Lua State.

luerl:dofile(Path, State) -> {ok, Result, NewState} | {lua_error, Error,
State} | CompileError
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’)”).

luerl:dofile_dec(Path[, State]) -> {ok, Result, NewState} | {lua_error, Er‐
ror, State} | CompileError
Load and execute the Lua code in the file and return its result which
is automatically decoded, and the new Lua State.

luerl:call(FuncRef, ArgRefs, State) -> {ok, Result, State}
luerl:call_chunk(FuncRef, ArgRefs, State) -> {ok, Result, State} | {lua_er‐
ror, Error, 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 en‐
luerl:call_function(FuncRef | FuncPath, ArgRefs, State] -> {ok, Result,
State} | {lua_error, Error, State}
Call a function already defined in the state. Result is NOT decoded.

luerl:call_function_dec(KeyPath, Args, State) -> {ok, Result, State} |
{lua_error, Error, State}
Call a function already defined in the state. KeyPath is a list of
keys to the function. KeyPath, Args and Result are automatically en‐
coded/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 encoded/decod‐
ed.
luerl:call_method(ObjRef, Method, ArgRefs, State) -> {ok, Result, State} |
{lua_error, Error, State}
Call a method already defined in the state.

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 en‐
luerl:call_method_dec(KeyPath, Method, Args, State) -> {ok, Result, State}
| {lua_error, Error, State}
Call a method already defined in the state. KeyPath is a list of keys
to the method. KeyPath, Method, Args and Result are automatically en‐
coded/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 encoded/decoded.
luerl:get_table_keys(KeyPath, State) -> {ok, Result, State} | {lua_error,
Error, State}
Gets a value inside the Lua state. KeyPath and Result are NOT en‐
coded/decoded.

luerl:stop(State) ‐> GCedState.
Garbage collects the state and (todo:) does away with it.
luerl:get_table_keys_dec(KeyPath, State) -> {ok, Result, State} | {lua_er‐
ror, Error, State}
Gets a value inside the Lua state. KeyPath is automatically encoded
and Result is decoded.

luerl:gc(State) ‐> State.
Runs the garbage collector on a state and returns the new state.
luerl:set_table_keys(KeyPath, Value, State) -> {ok,State} | {lua_error, Er‐
ror, State}
Sets a value inside the Lua state. KeyPath and Value are NOT encoded.

luerl:set_table(KeyPath, Value, State) ‐> State.
Sets a value inside the Lua state. Value is automatically encoded.
luerl:set_table_keys_dec(KeyPath, Value, State) -> {ok, Result, State} |
{lua_error, Error, State}
Sets a value inside the Lua state. KeyPath and Value are automatically
encoded and Result is decoded.

luerl:set_table1(KeyPath, Value, State) ‐> State.
Sets a value inside the Lua state. KeyPath and Value are NOT encoded.
luerl:get_table_key(Table, Key, State) -> {ok, Result, State} | {lua_error,
Error, State}
Gets the value of a key in a table. Table and Key are NOT encoded and
Result is NOT decoded.

luerl:get_table(KeyPath, State) ‐> {Result,State}.
Gets a value inside the Lua state. KeyPath and Result are automatical‐
ly encoded.
luerl:set_table_key(Table, Key, Value, State) -> {ok, State} | {lua_error,
Error, State}
Sets the value of a key in a table. Table, Key and Value are NOT en‐
coded.

luerl:get_table1(KeyPath, State) ‐> {Result,State}.
Gets a value inside the Lua state. KeyPath and Result are NOT encod‐
ed/decoded.
luerl:get_stacktrace(State) -> [{FuncName,{file,FileName},{line,Line}}]
Return a stack trace of the current call stack in the state.

You can use this function to expose an function to the Lua code by us‐
ing this interface: fun(Args, State) ‐> {Results, State}
luerl:encode(Term, State) -> {LuerlTerm,State}
Encode the Erlang representation of a term into Luerl form updating the
state when necessary.

Args and Results must be a list of Luerl compatible Erlang values.
luerl:encode_list([Term], State) -> {[LuerlTerm],State}
Encode a list of Erlang term representations into a list of Luerl forms
updating the state when necessary.

AUTHORS
Jean Chassoul, Robert Virding.
luerl:decode(LuerlTerm, State) -> Term
Decode a term in the Luerl form into its Erlang representation.

luerl:decode_list([LuerlTerm], State) -> [Term]
Decode a list of Luerl terms into a list of Erlang representations.

AUTHORS
Jean Chassoul, Robert Virding.

2018‐2023 luerl(3)
2018-2024 luerl(3)
137 changes: 137 additions & 0 deletions doc/luerl_old.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
luerl_old(3) Library Functions Manual luerl_old(3)

Name
luerl - The old original interface to the Luerl system

Interface functions
The Lua State parameter is the state of a Lua VM instance. It must be
created with the luerl:init() call and be carried from one call to the
next.

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 will generate an error
when they would 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.

Note that Lua Chunks (see definition below) can travel between differ‐
ent States. They are precompiled bits of code, independent of State.
That you can ‘carry around’ this is no unique to Luerl but a low-level
implementation detail of the standard Lua language ⟨https://lua.org⟩,
for more on chunks read ⟨https://www.lua.org/manual/5.3/man‐
ual.html#3.3.2⟩ the official Lua 5.3 reference manual
⟨https://www.lua.org/manual/5.3/manual.html⟩.

Spec Definitions
Binary means an Erlang binary string.
Chunks means a portion of precompiled bytecode.
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 means Lua table keys, the keys of a key-value structure.

Functions
eval and do functions differ only in what they return. The do func‐
tions 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}

luerl:eval(String|Binary|Form, State) -> {ok, Result} | {error, Reason,
StackTrace}.
Evaluate a Lua expression passed in as a string or binary, and return
its result.

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

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(‘File‐
Name’)”).

luerl:load(String|Binary[, CompileOptions], State) -> {ok,Function,New‐
State} | {error, Reason}.
Parse a Lua chunk as string or binary, and return a compiled chunk
(‘form’).

luerl:loadfile(FileName[, CompileOptions], State) -> {ok,Function,NewState}
| {error, Reason}.
Parse a Lua file, and return a compiled chunk (‘form’).

luerl:path_loadfile([Path, ], FileName[, CompileOptions], State) ->
{ok,Function,FullName,State} | {error, Reason}.
Search Path until the file FileName is found. Parse the file and re‐
turn a compiled chunk (‘form’). If Path is not given then the path de‐
fined in the environment variable LUA_LOAD_PATH is used.

luerl:load_module(KeyPath, ErlangModule, State) -> State.
Load ErlangModule and install its table at KeyPath which is encoded.

luerl:load_module1(KeyPath, ErlangModule, State) -> State.
Load ErlangModule and install its table at KeyPath which is NOT encoded

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 en‐
coded/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 encoded/de‐
coded.

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 en‐
coded/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 encoded/decoded.

luerl:stop(State) -> GCedState.
Garbage collects the state and (todo:) does away with it.

luerl:gc(State) -> State.
Runs the garbage collector on a state and returns the new state.

luerl:set_table(KeyPath, Value, State) -> State.
Sets a value inside the Lua state. Value is automatically encoded.

luerl:set_table1(KeyPath, Value, State) -> State.
Sets a value inside the Lua state. KeyPath and Value are NOT encoded.

luerl:get_table(KeyPath, State) -> {Result,State}.
Gets a value inside the Lua state. KeyPath and Result are automati‐
cally encoded.

luerl:get_table1(KeyPath, State) -> {Result,State}.
Gets a value inside the Lua state. KeyPath and Result are NOT en‐
coded/decoded.

You can use this function to expose an function to the Lua code by us‐
ing this interface: fun(Args, State) -> {Results, State}

Args and Results must be a list of Luerl compatible Erlang values.

AUTHORS
Jean Chassoul, Robert Virding.

2018-2024 luerl_old(3)
Loading