luerl_new(3)                                                      luerl_new(3)



Interface functions ‐ New Version
       The  Lua State parameter is the state of a Lua VM instance.  It must be
       created with the luerl_new: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/manu‐
       al.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.

       LuaCallReturn = {ok, Result, State} | {lua_error, Error, State}
       This is the return value from evaluating a Lua call.

   Functions
   luerl_new:init() ‐> State.
       Get a new Lua State = a fresh Lua VM instance.

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

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

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

   luerl_new: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_new:load_module(KeyPath, ErlangModule, State) ‐> State.
       Load  ErlangModule and install its table at KeyPath which is NOT encod‐
       ed.

   luerl_new:load_module_dec(EncodedKeyPath, ErlangModule, State) ‐> State.
       Load ErlangModule and install its table at KeyPath which is encoded.

   luerl_new: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_new: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_new:dofile(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  NOT  decoded,  and  the  new  Lua  State.   Equivalent   to   doing
       luerl:do(“return dofile(‘FileName’)”).

   luerl_new:dofile_dec(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 automatically decoded, and the new Lua State.

   luerl_new:call(FuncRef, ArgRefs, State) ‐> {ok, Result, State}
   luerl_new:call_chunk(FuncRef,  ArgRefs,  State)  ‐>  {ok,  Result, State} |
       {lua_error, Error, State}.
       Call a compiled chunk or function.  Use the call_chunk, call  has  been
       kept for backwards compatibility.

   luerl_new:call_function(FuncRef,  ArgRefs,  State] ‐> {ok, Result, State} |
       {lua_error, Error, State}.
       Call a function already defined in the state.  Result is NOT decoded.

   luerl_new: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_new:call_method(ObjRef,  Method,  ArgRefs,  State)  ‐>  {ok,  Result,
       State} | {lua_error, Error, State}.
       Call a method already defined in the state.

   luerl_new: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_new:get_table_keys(KeyPath,  State) ‐> {ok, Result, State} | {lua_er‐
       ror, Error, State}.
       Gets a value inside the Lua state.  KeyPath and Result are  NOT  encod‐
       ed/decoded.

   luerl_new:get_table_keys_dec(KeyPath,  State)  ‐>  {ok,  Result,  State}  |
       {lua_error, Error, State}.
       Gets a value inside the Lua state.  KeyPath and Result are automatical‐
       ly encoded/decoded.

   luerl_new:set_table_keys(KeyPath, Value, State) ‐> State.
       Sets  a value inside the Lua state.  KeyPath and Value are NOT encoded.

   luerl_new:set_table_keys_dec(KeyPath, Value, State) ‐> State.
       Sets a value inside the Lua state.  KeyPath and Value are automatically
       encoded.

   luerl_new:get_stacktrace(State)          ‐>          [{FuncName,{file,File‐
       Name},{line,Line}}].
       Return a stack trace of the current call stack in the state.

   luerl_new:encode(Term, State) ‐> {LuerlTerm,State}.
       Encode the Erlang representation of a term into Luerl form updating the
       state when necessary.

   luerl_new:encode_list([Term], State) ‐> {[LuerlTerm],State}.
       Encode a list of Erlang term representations into a list of Luerl forms
       updating the state when necessary.

   luerl_new:decode(LuerlTerm, State) ‐> Term.
       Decode a term in the Luerl form into its Erlang representation.

   luerl_new: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_new(3)
