Update the documentation wrt to old and new

doc/luerl.txt

@@ -161,6 +161,15 @@ Interface functions - New Version
    luerl:decode_list([LuerlTerm], State) -> [Term]
        Decode a list of Luerl terms into a list of Erlang representations.
 
+   luerl:put_private(Key, Term, State) -> State.
+       Puts a private value under key that is not exposed to the runtime.
+
+   luerl:get_private(Key, State) -> Term.
+       Get a private value for the given key.
+
+   luerl:delete_private(Key, State) -> Term.
+       Deletes the private value for the given key.
+
 AUTHORS
        Jean Chassoul, Robert Virding.
 

doc/luerl_sandbox.txt

@@ -1,51 +1,49 @@
-luerl_sandbox(3)                                              luerl_sandbox(3)
-
-
+luerl_sandbox(3)           Library Functions Manual           luerl_sandbox(3)
 
 Name
-       luerl_sandbox ‐ Fuctions for sandboxing Luerl evaluation
+       luerl_sandbox - Fuctions for sandboxing Luerl evaluation
 
 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,
+       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.
+       Keys means Lua table keys, the keys of a key-value structure.
 
    Functions
-   init() ‐> State.
-   init([ State | TablePaths]) ‐> State.
-   init(State, TablePaths) ‐> State.
-       Create  a new sandboxed state.  If a state is given as an argument then
-       that state will be used  otherwise  a  new  default  be  be  generated.
-       TablePaths  is  a list of paths to functions which will be blocked.  If
+   init() -> State.
+   init([ State | TablePaths]) -> State.
+   init(State, TablePaths) -> State.
+       Create a new sandboxed state.  If a state is given as an argument  then
+       that  state  will  be  used  otherwise  a  new default be be generated.
+       TablePaths is a list of paths to functions which will be  blocked.   If
        none is given then the default list will be used.
 
-   run(String | Binary) ‐> {Result, State} | {error, Reason}.
-   run(String | Binary, State) ‐> {Result, State} | {error, Reason}.
-   run(String | Binary, Flags, State) ‐> {Result, State} | {error, Reason}.
+   run(String | Binary) -> {Result, State} | {error, Reason}.
+   run(String | Binary, State) -> {Result, State} | {error, Reason}.
+   run(String | Binary, Flags, State) -> {Result, State} | {error, Reason}.
        Spawn a new process which runs the string String in State where the de‐
        fault  sandbox  state will be used if none is given.  Flags is a map or
        keyword list which can contain the following fields
@@ -55,19 +53,19 @@ Interface Functions
                 spawn_opts => SpawnOpts}
 
        MaxReds limits the number of reductions and MaxTime (default 100 msecs)
-       the  time to run the string, SpawnOpts are spawn options to the process
+       the time to run the string, SpawnOpts are spawn options to the  process
        running the evaluation.
 
-   run(String | Binary) ‐> {Result, State} | {error, Reason}.
-   run(String | Binary, State) ‐> {Result, State} | {error, Reason}.
-   run(String | Binary, State, [ MexReds | Flags ]) ‐> {Result, State} |  {er‐
+   run(String | Binary) -> {Result, State} | {error, Reason}.
+   run(String | Binary, State) -> {Result, State} | {error, Reason}.
+   run(String  | Binary, State, [ MexReds | Flags ]) -> {Result, State} | {er‐
        ror, Reason}.
-   run(String  |  Binary,  State, MexReds, Flags) ‐> {Result, State} | {error,
+   run(String | Binary, State, MexReds, Flags) -> {Result,  State}  |  {error,
        Reason}.
-   run(String | Binary, State, MexReds, Flags, Timeout) ‐> {Result,  State}  |
+   run(String  |  Binary, State, MexReds, Flags, Timeout) -> {Result, State} |
        {error, Reason}.
        This is the old interface to run.  It still works but the new interface
-       is recommendded.  Spawn a new process which runs the string  String  in
+       is recommended.  Spawn a new process which runs the  string  String  in
        State  where  the  default sandbox state will be used if none is given.
        MaxReds limits the number of reductions and TimeOut (default 100 msecs)
        the time to run the string, Flags are spawn options to the process run‐
@@ -76,6 +74,4 @@ Interface Functions
 AUTHORS
        Robert Virding.
 
-
-
                                      2023                     luerl_sandbox(3)

doc/man/luerl.3

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.5
+.\" Automatically generated by Pandoc 3.6
 .\"
 .TH "luerl" "3" "2018\-2024" ""
 .SH Name
@@ -154,5 +154,11 @@ updating the state when necessary.
 Decode a term in the Luerl form into its Erlang representation.
 .SS luerl:decode_list([LuerlTerm], State) \-> [Term]
 Decode a list of Luerl terms into a list of Erlang representations.
+.SS luerl:put_private(Key, Term, State) \-> State.
+Puts a private value under key that is not exposed to the runtime.
+.SS luerl:get_private(Key, State) \-> Term.
+Get a private value for the given key.
+.SS luerl:delete_private(Key, State) \-> Term.
+Deletes the private value for the given key.
 .SH AUTHORS
 Jean Chassoul, Robert Virding.

doc/man/luerl_old.3

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.5
+.\" Automatically generated by Pandoc 3.6
 .\"
 .TH "luerl_old" "3" "2018\-2024" ""
 .SH Name

doc/man/luerl_sandbox.3

@@ -1,47 +1,38 @@
-.\" Automatically generated by Pandoc 3.1.6.1
+.\" Automatically generated by Pandoc 3.6
 .\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "luerl_sandbox" "3" "2023" "" ""
-.hy
+.TH "luerl_sandbox" "3" "2023" ""
 .SH Name
-.PP
-luerl_sandbox - Fuctions for sandboxing Luerl evaluation
+luerl_sandbox \- Fuctions for sandboxing Luerl evaluation
 .SH Interface Functions
-.PP
 The \f[B]Lua State\f[R] parameter is the state of a Lua VM instance.
 It must be created with the \f[B]luerl:init()\f[R] call and be carried
 from one call to the next.
 .PP
-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
-\f[B]\f[VB]_G\f[B]\f[R] which references the top-level table.
+\f[B]\f[CB]_G\f[B]\f[R] which references the top\-level table.
 .PP
 Note that Lua \f[B]Chunks\f[R] (see definition below) can travel between
 different 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/manual.html#3.3.2) the official Lua
-5.3 reference manual (https://www.lua.org/manual/5.3/manual.html).
+That you can `carry around' this is no unique to Luerl but a low\-level
+implementation detail of the standard Lua \c
+.UR https://lua.org
+language
+.UE \c
+, for more on chunks \c
+.UR https://www.lua.org/manual/5.3/manual.html#3.3.2
+read
+.UE \c
+\ the official Lua 5.3 \c
+.UR https://www.lua.org/manual/5.3/manual.html
+reference manual
+.UE \c
+\&.
 .SS Spec Definitions
-.PP
 \f[B]Binary\f[R] means an Erlang binary string.
 .PD 0
 .P
@@ -63,52 +54,49 @@ nested names, e.g.\ [table,pack] for table.pack.
 .PD 0
 .P
 .PD
-\f[B]Keys\f[R] means Lua table keys, the keys of a key-value structure.
+\f[B]Keys\f[R] means Lua table keys, the keys of a key\-value structure.
 .SS Functions
-.SS init() -> State.
-.SS init([ State | TablePaths]) -> State.
-.SS init(State, TablePaths) -> State.
-.PP
+.SS init() \-> State.
+.SS init([ State | TablePaths]) \-> State.
+.SS init(State, TablePaths) \-> State.
 Create a new sandboxed state.
 If a state is given as an argument then that state will be used
 otherwise a new default be be generated.
-\f[V]TablePaths\f[R] is a list of paths to functions which will be
+\f[CR]TablePaths\f[R] is a list of paths to functions which will be
 blocked.
 If none is given then the default list will be used.
-.SS run(String | Binary) -> {Result, State} | {error, Reason}.
-.SS run(String | Binary, State) -> {Result, State} | {error, Reason}.
-.SS run(String | Binary, Flags, State) -> {Result, State} | {error, Reason}.
-.PP
-Spawn a new process which runs the string \f[V]String\f[R] in
-\f[V]State\f[R] where the default sandbox state will be used if none is
+.SS run(String | Binary) \-> {Result, State} | {error, Reason}.
+.SS run(String | Binary, State) \-> {Result, State} | {error, Reason}.
+.SS run(String | Binary, Flags, State) \-> {Result, State} | {error, Reason}.
+Spawn a new process which runs the string \f[CR]String\f[R] in
+\f[CR]State\f[R] where the default sandbox state will be used if none is
 given.
-\f[V]Flags\f[R] is a map or keyword list which can contain the following
-fields
+\f[CR]Flags\f[R] is a map or keyword list which can contain the
+following fields
 .IP
-.nf
-\f[C]
+.EX
 #{max_time => MaxTime,
   max_reductions => MaxReds,
   spawn_opts => SpawnOpts}
-\f[R]
-.fi
-.PP
-\f[V]MaxReds\f[R] limits the number of reductions and \f[V]MaxTime\f[R]
-(default 100 msecs) the time to run the string, \f[V]SpawnOpts\f[R] are
-spawn options to the process running the evaluation.
-.SS run(String | Binary) -> {Result, State} | {error, Reason}.
-.SS run(String | Binary, State) -> {Result, State} | {error, Reason}.
-.SS run(String | Binary, State, [ MexReds | Flags ]) -> {Result, State} | {error, Reason}.
-.SS run(String | Binary, State, MexReds, Flags) -> {Result, State} | {error, Reason}.
-.SS run(String | Binary, State, MexReds, Flags, Timeout) -> {Result, State} | {error, Reason}.
+.EE
 .PP
+\f[CR]MaxReds\f[R] limits the number of reductions and
+\f[CR]MaxTime\f[R] (default 100 msecs) the time to run the string,
+\f[CR]SpawnOpts\f[R] are spawn options to the process running the
+evaluation.
+.SS run(String | Binary) \-> {Result, State} | {error, Reason}.
+.SS run(String | Binary, State) \-> {Result, State} | {error, Reason}.
+.SS run(String | Binary, State, [ MexReds | Flags ]) \-> {Result, State} | {error, Reason}.
+.SS run(String | Binary, State, MexReds, Flags) \-> {Result, State} | {error, Reason}.
+.SS run(String | Binary, State, MexReds, Flags, Timeout) \-> {Result, State} | {error, Reason}.
 This is the old interface to run.
 It still works but the new interface is recommended.
-Spawn a new process which runs the string \f[V]String\f[R] in
-\f[V]State\f[R] where the default sandbox state will be used if none is
+Spawn a new process which runs the string \f[CR]String\f[R] in
+\f[CR]State\f[R] where the default sandbox state will be used if none is
 given.
-\f[V]MaxReds\f[R] limits the number of reductions and \f[V]TimeOut\f[R]
-(default 100 msecs) the time to run the string, \f[V]Flags\f[R] are
-spawn options to the process running the evaluation.
+\f[CR]MaxReds\f[R] limits the number of reductions and
+\f[CR]TimeOut\f[R] (default 100 msecs) the time to run the string,
+\f[CR]Flags\f[R] are spawn options to the process running the
+evaluation.
 .SH AUTHORS
 Robert Virding.