Blitz Lua Object Interface

wiki

BlitzLua Object Interface

The "object interface" directly maps BlitzMAX types to a corresponding Lua "class", i.e., a table with an associated metatable. All tyes of a given BlitzMAX module reside in a Lua table whose name is that of the underlying module: e.g., under Lua, the BlitzMAX type TGadget found in module BRL.MaxGUI is replicated by brl.maxgui.TGadget (with brl being a global table). An optional "import" mechanism makes all types of a given module global, removing the need to prefix them with their module name.

Naming Conventions

Since Lua is a case-sensitive language (whereas BlitzMAX is not) the following naming conventions apply:

• all module names are in lowercase
• the casing of BlitzMAX type and method names is kept - with the following exceptions:
  • method names starting with a verb or an adjective begin with a lowercase letter
  • all other names start with a capital letter

In case of any incertitudes just consider the type reference which is part of the package.

Parameter Handling and Type Conversion

The Lua function parameters equal those of the corresponding BlitzMAX method, any default values are properly respected (i.e., the corresponding Lua argument may be nil). Types are converted as follows:

• BlitzMAX strings are passed to Lua as C strings - and vice-versa (this currently prevents the use of 16-bit character sets and will probably be changed in the future. For the moment, this approach has been chosen in order to avoid problems with wide-characters, which have been reported for MaxGUI)
• numeric BlitzMAX values are always passed to Lua as double-precision floating point numbers - and vice-versa (this works quite well even for "long integers" in the range - 9007199254740994...+9007199254740994 [1])
• whenever BlitzMAX expects or returns a logical value, the corresponding Lua value must be (or will be) of type "boolean"
• whenever BlitzMAX expects or returns a byte array, the corresponding Lua value must be (or will be) of type "string"
• instead of BlitzMAX objects corresponding Lua "objects" are passed (read the note below!)

Additionally,

• "variable parameters" are returned one after the other (in the same order as they appear in the parameter list) in addition to and after the primary function return value (if such exists)
• whenever BlitzMAX expects an array of a given type (besides byte), Lua has to provide a numerically indexed table with elements of the required element type
• whenever BlitzMAX originally returns an array of values (not of type byte), the corresponding interface function passes an "unpacked" list of values to the calling Lua script

Noteworthy detail: while the "function interface" passes BlitzMAX objects as "light userdata", the "object interface" works with Lua "objects" only. As a consequence, the interface implements a look-up technique in order to retrieve the Lua table for a given BlitzMax object and vice-versa:

• every Lua "object" owns a field called "_Peer" which contains a "reference" to the underlying BlitzMAX object (do not modify this field!)
• the interface also handles a look-up-table containing the associated Lua table for every existing BlitzMAX object

It is therefore the "_Peer" which is passed to a BlitzMAX function, whereas every object returned from BlitzMAX is looked-up and replaced by its associated Lua table (if such a table exists, otherwise a new one is created "on-the-fly")

Any BlitzMAX constants are also available within the table belonging to the defining module - their names have been kept in uppercase (e.g. brl.event.EVENT_WINDOWCLOSE) as under BlitzMAX.

Some Details of the Object Interface

The interface "classes" provide prototype-based differential inheritance (which actually means, that modifying a "class" immediately affects all its instances, unless the modified field is "shadowed" by the instance). Additionally, they manage the lifespan of their "_Peer": using "keepers" (see BlitzLuaKeeper), every Lua "object" gets informed by the garbage collector when it is to be removed from memory. It then invokes its destroy method, which properly shuts down and removes the associated BlitzMAX peer.

When using both the "function interface" and the "object interface", you should not mix functions working on BlitzMAX objects and Lua "methods" unless you really know what you are doing. Using other functions (which do not deal with a specific object) is, however, safe (and often necessary)

Compared to the "function interface", the "object interface" allows for an object-oriented notation and frees the programmer from the burden of having to manage BlitzMAX objects him/herself.

The "object interface" has not yet been finished but will hopefully be published around May 18th, 2007.

--AndreasRozek