ANN: LuaState (A C++ Lua Wrapper and enhanced Lua 4.1 Distribution)

["Joshua Jensen" <jjensen@...>]

Since I am (sarcasm on) so great at coming up with clever names (sarcasm
off), this modified Lua distribution is called LuaState, after the main
C++ class in the distribution.

The LuaState distribution may be downloaded at:

http://workspacewhiz.com/Other/LuaState/LuaState.html
http://workspacewhiz.com/Other/LuaState/LuaState_LuaWrapper41Alpha.zip

Warning: The following distribution contains modified Lua 4.1 Alpha
code.
Many modifications are superficial, but some, such as the Unicode string
type, go quite a bit deeper.  It is my hope these changes will be
considered for inclusion into the master Lua distribution.

A new distribution will be released shortly for Lua 4.1 Beta Work.

The LuaState distribution provides the following functionality:

* All the power of the core Lua distribution.
* Unicode support.
* Custom memory allocators.
* Memory optimizations.
* Can be built into Win32 DLL or LIB form.
* Win32 multithreading.
* Unified methods.
* String formatting enhancements.
* Built-in raw pointer type.
* Serialization of Lua tables.
* An easy to use C++ wrapper.

See the Docs/LuaState.html for additional information.

Unicode
=======
Unicode (or rather, wide character) support is built-in as a native Lua
type.  While it is entirely possible to represent a Unicode string using
a regular Lua 8-bit clean string, there is no way of determining whether
the given string is Unicode or not.  The secondary problem involves the
use of standard string functionality, such as the concatenation
operator.  If a Unicode string is represented as a normal 8-bit Lua
string, special functions would have to be written to perform operations
on the string (i.e. concatenation of two Lua 8-bit clean strings which
represent Unicode).  Rather than confuse the user, a Unicode string type
is available.  The term Unicode is used loosely in this context (since
there are different standards of Unicode), but for the purposes of this
distribution, Unicode refers to 16-bit wide character support.

Memory Allocators
=================
This distribution replaces the #define approach to memory allocation
within Lua with a callback mechanism, where the memory allocators can be
replaced on a per Lua state basis.  This allows a powerful mechanism to
be employed to adjust memory allocation strategies on a per state basis.

Memory Optimizations
=====================
A whole host of functionality has been added to facilitate the
optimization of memory usage in a tight memory environment.

Multithreading
==============
Win32 multithreading is built into the LuaState distribution by default.

Fatal Error Handler
===================
Having exit() be called in non-command line apps is generally a bad
thing.  In some environments, exit() can't be called at all.  Rather
than have the application blow up in an undesirable fashion, the
LuaState distribution allows the fatal error exit() function in Lua to
be overridden through a call to lua_setfatalerrorfunction().  The
default fatal error callback runs the exit() function.  It can be
replaced as desired.

New String Formatting Enhancements
==================================
format has been extended with the following control types.  The use of
these control types makes it easy to write binary file formats to disk.

* format("%bb", 255) creates a string containing the 8-bit byte 255.
* format("%bw", 1000) creates a string containing the 16-bit word 1000.
* format("%bd", 1000000) creates a string containing the 32-bit dword
  1000000.
* format("%bf", 1.0f) creates a string containing the 32-bit float 1.0.
* format("%bF", 1.0) creates a string containing the 64-bit double 1.0.
* format("%Q", str) turns a binary string into a printable string.

Built-in Pointer Type
=====================
The LuaState distribution offers a built-in pointer type.  The pointer
type is used for just passing a raw pointer into Lua and back out to a C
function.

Unified Methods
===============
Unified methods are based heavily on Edgar Toernig's Sol implementation
of unified methods (note: some text is taken verbatim from the Sol
documentation).

Every object in Lua has an attached method table.  For C++ users, the
method table is most similar to a v-table.  For Lua's simple types (nil,
number, string, ustring, and function), there is one method table for
all objects of the given type.  Table and userdata objects have the
ability to have method tables on a per object basis.

Unlike Edgar's Sol implementation, the colon operator for Lua's
automatic self functions is not replaced with an alternate
implementation.  This is done in an effort to keep LuaState
functionality identical to the original Lua distribution.  Instead, two
new function operators are introduced.  The pointer symbol (->) behaves
like the colon operator, but it looks up the function to call in the
method table.  The second operator is the double colon operator, which
behaves like the regular dot operator (no self is passed in).

The biggest advantage of unified methods is memory savings.  When
dealing with many Lua objects (say, tables) of the same type, the
functions don't have to be duplicated for each and every one.
Significant amounts of memory may be saved by the use of the shared
method table.

Serializing
===========
The LuaState distribution can write out a Lua table in a nice, formatted
file.  The only downside to LuaState's approach is that the table can't
currently be cyclic.

A table can be written both from Lua and C++.  The function prototypes
are:

function WriteLuaFile(fileName, objectName, valueToWrite, indentLevel,
                      writeAll, alphabetical, maxIndentLevel)
function WriteLuaGlobalsFile(fileName, writeAll, alphabetical,
                      maxIndentLevel)
function WriteLuaObject(filePtr, objectName, valueToWrite, indentLevel,
                      writeAll, alphabetical, maxIndentLevel)