book.txt

1 Introduction
1.1 Library Design
  1.1.1 No Enums
  1.1.2 Memory Overhead
  1.1.3 Cleaning Up
  1.1.4 Multilua State
  1.1.5 Safety
2 Metamethods
2.1 Library Call
2.2 Length Operator
2.3 Index Operator
2.4 New Index Operator
2.5 Call Operator
3 Definitions
3.1 multilua.new
3.2 multilua.close
3.3 multilua.dump
3.4 multilua.openlibs
3.5 multilua.absindex
3.6 multilua.arith
3.7 multilua.fetchable
Index
1 Introduction
**************

1.1 Library Design
==================

The overall design of the library is such that it should mostly match
Lua 5.3’s C API, and thus be familiar to the programmer.

   The library generally follows one of the two forms:

multilua.function(multilua_state, ...)

multilua_state:function(...)

   Most functions will return ‘nil’ upon failure, and either some
result, or ‘true’ upon success. This should allow the programmer to wrap
most function calls inside either some sort of error handling, or a
simple ‘assert’.

   However there are some differences to the C-API, and some design
challenges, that the programmer should be aware of.

1.1.1 No Enums
--------------

When it comes to places where Lua would usually make use of an ‘enum’,
we instead tend to make use of strings, as would usually be done from
the Lua side of things.

   For example:

local multilua = require "multilua"

local obj = assert(multilua.new())

obj:pushinteger(10)
obj:pushinteger(11)
print(obj:compare(-1, -2, "=="))

   Usually, in the C-API, you would pass ‘LUA_OPEQ’, but instead, we
pass the string ‘"=="’.

1.1.2 Memory Overhead
---------------------

To simplify making use of the API, and to prevent a number of memory
errors, ‘multilua’ will call ‘lua_checkstack’ for you automatically.

   Whilst this makes it much safer to use the API, it also means that
‘multilua’ may sometimes use more memory than is strictly necessary.

   Whilst the overhead does not tend to be significant, there is some
overhead, and the programmer may care about that.

   There is also a couple bytes (literally) reserved for the object
state, which adds to the memory overhead.

1.1.3 Cleaning Up
-----------------

‘multilua’ states are Garbage-Collected values.

   This means that whilst you can cleanup a state when you don’t need it
anymore, by calling the close method, the host Lua’s Garbage Collector
will also call this method when it feels the need to get rid of a
‘multilua’ state.

   Like all GC collections, this may have performance ramifications for
your program - which you can work around by calling close yourself.

   This also causes any reference types to be cleaned up - some of which
may have been borrowed by various other states. In which case... Welcome
to the terrifying land of _Undefined Behaviour_. (There’s a reason we
call them reference types!)

1.1.4 Multilua State
--------------------

The ‘multilua’ state object is a userdata, with a bunch of methods
attached to it, and a single value located at the key ‘"self"’.

   This ‘"self"’ value is a lightuserdata value. If the programmer feels
the need to modify or play with this in any way, shape, or form, then
they will be entering the terrifying land of Undefined Behaviour, and
nobody can help them.

   In short: don’t touch it.

   However, if you are keen on messing with things, and possessing less
than average intelligence, then the "self" value is actually what it
seems like - a C-pointer to a lua_State.

   Note: In the case of an invalid ‘multilua’ state (such as one that
has been manually closed), then "self" may actually be ‘nil’.

1.1.5 Safety
------------

Whilst ‘multilua’ does attempt to protect you from doing downright
idiotic things, quite a lot of the API is still using memory pointers,
which are treated exactly as what they are.

   This means if the programmer does something idiotic, like passing the
wrong kind of pointer to the wrong function, they will still have things
misbehave as if they had done that in C.

   Which, unfortunately, means segmentation faults, memory corruption
errors, and all sorts of other goodies are entirely possible.

   ‘multilua’ cannot protect you against everything.

   It explicitly _will not_ protect you if you allow the originating
state to clean up a reference value that you’re using in another Lua
state, including the host state.

   For example, this will result in _Undefined Behaviour_ (probably a
segmentation fault), as a reference is not maintained by the originating
state:

local multilua = require "multilua"

local obj = multilua.new()

obj[#obj + 1] = {hello = "world"}
collectgarbage("collect")

t = obj(-1)
print(#t)

   There is no way for ‘obj’ to know that the host Lua has
garbage-collected the original table value. And no way for the host Lua
to know that it shouldn’t collect the value - it doesn’t see it inside
its own state.

2 Metamethods
*************

‘multilua’ includes a variety of metamethods to make programming feel
simpler, and closer to what one would expect in Lua, instead of only
like the C-API.

   These metamethods in no way restrict the power of what you can do -
they simple abstract away some of the fiddlier bits of the API.



                                 — — —


2.1 Library Call
================

Calling the library object is a short hand for calling ‘multilua.new’.

local multilua = require "multilua"

local obj = multilua()



                                 — — —


2.2 Length Operator
===================

Lua’s length operator has been overridden to match ‘multilua.gettop’,
that is, it’ll return the current size of the stack for the given
multilua state object.

local multilua = require "multilua"

local obj = multilua.new()

assert(#obj == obj:gettop())



                                 — — —


2.3 Index Operator
==================

Lua’s index fetching has been overridden so that ‘integer’ keys will
return the type found at that position on the stack, for a given
multilua state object. String keys will continue to operate as expected.
Other types of keys are not accepted.

local multilua = require "multilua"

local obj = multilua.new()

obj:pushstring("Hello")

assert(obj[-1] == 'string')



                                 — — —


2.4 New Index Operator
======================

Lua’s new index operator has been overridden so that ‘integer’ keys will
operate on the stack, for a given multilua state object. String keys
will continue to operate as expected. Other types of keys are not
accepted.

   _WARNING_: If a value being passed cannot simply be copied, it will
push a _reference_.

   This can currently copy the current values:

   • ‘nil’
   • ‘integer’
   • ‘number’
   • ‘boolean’
   • ‘string’
   • ‘CFunction’
   • ‘lightuserdata’

   Other types will be sent as _reference_s.

   _WARNING_: Invalid indicies may raise errors.

local multilua = require "multilua"

local obj = multilua.new()

obj[#obj + 1] = 10



                                 — — —


2.5 Call Operator
=================

The ‘metalua’ state object can be called, with an argument of the index,
to return a copyable value from the stack. This value is not modified or
popped.

   See also, *note multilua.fetchable: Definitions.

   _WARNING_: For Lua functions, tables, full userdata, threads, if the
originating state is closed, and then they are attempted to be used,
will result in _Undefined Behaviour_. This is because those values are
‘reference’ types, as is normal in Lua.

local multilua = require "multilua"

local obj = multilua.new()

obj[#obj + 1] = 10

assert(obj(-1) == 10)

3 Definitions
*************

3.1 multilua.new
================

 -- Function: multilua.new -> nil|userdata

     This function attempts to create a fresh ‘multilua’ state object.

     Returns:

        • ‘nil’ - Something went wrong. Probably a memory error.
        • ‘userdata’ - The ‘multilua’ state object.

     The ‘userdata’ object should have a ‘metatable’.



                                 — — —


3.2 multilua.close
==================

 -- Function: multilua.close <userdata:state> -> boolean|nil

     This function, given a ‘multilua’ ‘state’, closes the state.

     ‘state['self']’ should become ‘nil’ after this function is called.

     WARNING: This function invokes a garbage collection on ‘state’, and
     therefore may have a performance impact.

     WARNING: If the ‘state’ is the host Lua’s ‘state’, this function is
     a no-op.

     Note: Whilst the ‘state’ attempts to prove that it is closed, use
     after closing should be considered a code smell.

     Returns:

        • ‘true’ - if the state was successfully closed.
        • ‘nil’ - if the state could not be closed.



                                 — — —


3.3 multilua.dump
=================

 -- Function: multilua.dump <userdata:state> -> boolean|nil

     This function, given a valid ‘multilua’ ‘state’, attempts to dump
     the current ‘stack’ to ‘stdout’ of the terminal.

     WARNING: This function is primarily meant for debugging. The output
     format is meant for human consumption, and is not guaranteed in any
     way, shape, or form.

     Returns:

        • ‘true’ - if the dump successfully took place.
        • ‘nil’ - if the state was somehow invalid.



                                 — — —


3.4 multilua.openlibs
=====================

 -- Function: multilua.openlibs <userdata:state> -> boolean|nil

     This function, given a valid ‘multilua’ ‘state’, attempts to open
     all standard Lua libraries into the given ‘state’.

     Returns:

        • ‘true’ - if the open successfully took place.
        • ‘nil’ - if the state was somehow invalid.



                                 — — —




                                 — — —


3.5 multilua.absindex
=====================

 -- Function: multilua.absindex <userdata:state> <integer:index> ->
          integer|nil

     This function, given a valid ‘multilua’ ‘state’, attempts to
     convert ‘index’ from a relative position (such as ‘-1’), to the
     absolute position.

     Returns:

        • ‘integer’ - The absolute position equivalent to the relative
          position given.
        • ‘nil’
             • If the ‘state’ was somehow invalid.
             • If the ‘index’ was somehow invalid.



                                 — — —


3.6 multilua.arith
==================

 -- Function: multilua.arith <userdata:state> <string:operator> ->
          number|nil

     This function, given a valid ‘multilua’ ‘state’, performs an
     arithmetic or bitwise operation on the one or two values at the top
     of the ‘stack’ for the given ‘state’.

     In the case of an invalid ‘multilua’ ‘state’, returns ‘nil’.

     _WARNING_: In the case of an ‘operator’ not listed below, Undefined
     Behaviour results.

     If the ‘operator’ is:

        • ‘"+"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs addition on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"-"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs subtraction on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"-u"’
             • Pops one numeric value from the ‘state’’s ‘stack’, and
               performs negation on the value.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"*"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs multiplication on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"/"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs floating point division on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"//"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs floor division on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’, then it is returned by the
               function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"%"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs a modulo operation on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"^"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs a exponention operation on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"&"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs a bitwise AND operation on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"|"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs a bitwise OR operation on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"<"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs a bitwise LEFT SHIFT operation on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘">"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs a bitwise RIGHT SHIFT operation on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"~"’
             • Pops two numeric values from the ‘state’’s ‘stack’, and
               performs a bitwise XOR (exclusive OR) operation on them.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.
        • ‘"~|"’
             • Pops one numeric value from the ‘state’’s ‘stack’, and
               performs a bitwise NOT operation on it.
             • The result is pushed to the ‘state’’s ‘stack’.
             • If the result is an ‘integer’ or ‘float’, then it is
               returned by the function.
                  • Otherwise, ‘nil’ is returned.



                                 — — —


3.7 multilua.fetchable
======================

 -- Function: multilua.fetchable <userdata:state> [<integer:index>] ->
          nil|boolean

     Given a ‘multilua state’ and a valid ‘index’, returns whether or
     not the value can be _safely_ copied from ‘state’ to the host Lua
     state.

     If no ‘index’ is provided, defaults to ‘-1’.

     Returns:

        • ‘nil’ - An error ocurred.
             • The ‘index’ may be invalid.
             • The ‘state’ may be invalid.
        • ‘false’ - The value cannot be safely copied. You will need to
          manually deepcopy it, or you will receive only a reference.
        • ‘true’ - The value can be safely copied.

Index
*****

* Menu:

* chapter, Definitions:                  Definitions.         (line 285)
* chapter, Introduction:                 Introduction.        (line  24)
* chapter, Metamethods:                  Metamethods.         (line 160)
* function, multilua.absindex:           Definitions.         (line 381)
* function, multilua.arith:              Definitions.         (line 404)
* function, multilua.close:              Definitions.         (line 308)
* function, multilua.dump:               Definitions.         (line 336)
* function, multilua.fetchable:          Definitions.         (line 525)
* function, multilua.new:                Definitions.         (line 289)
* function, multilua.openlibs:           Definitions.         (line 358)
* multilua state:                        Definitions.         (line 300)
* multilua.absindex:                     Definitions.         (line 381)
* multilua.arith:                        Definitions.         (line 404)
* multilua.close:                        Definitions.         (line 308)
* multilua.dump:                         Definitions.         (line 336)
* multilua.fetchable:                    Definitions.         (line 525)
* multilua.new:                          Definitions.         (line 289)
* multilua.openlibs:                     Definitions.         (line 358)