LuaPlus

h1. LuaPlus

The source code may be downloaded from the new Git repository:

<pre>

git clone git://github.com/jjensen/luaplus51-all.git

</pre>

h2. Building

# Run the @CreateJamVS2010Workspace.bat@ (or @CreateJamVS2008Workspace.bat@ or @CreateJamXcodeWorkspace.sh@) script in the LuaPlus main directory after putting the @jamplus\bin\win32@ directory in your @PATH@ (or modifying the @CreateJamVS2010Workspace.bat@ script to point to that directory).

# Navigate to @build2010\_workspace.vs2010_\@ and open @LuaPlus.sln@ within Visual Studio 2010.

# Build the solution.

h2. What is LuaPlus?

_The LuaPlus distribution contains some modifications to the core Lua code base.  As such, it is not an official distribution of Lua 5.1 (which may be found at http://www.lua.org/), nor does it intend to represent itself as one.  Most modifications are superficial, but some, such as the wide character string type, end up touching a great deal of source files.  Any references to Lua in this document refer specifically to the modified Lua code contained herein, unless otherwise stated._

The LuaPlus distribution provides the following functionality.

* All the power of the core Lua 5.1 work distribution.

* An optional high performance reference counted garbage collector.

* An easy to use C++ interface:

** The C++ interface, described below, masks many of the intricacies of core Lua's underlying low-level C API.  In particular, stack management is mostly ignored.  Other useful helper classes, such as management of ref'ed objects or the stack, table traversal, and table lookups are provided, dramatically simplifying the application code.

** Simplified function calling convention.  Inspired by, to a limited degree, Python's use of tuples in its C API, the new function calling convention masks the stack pushing and popping associated with the low-level calling convention.

** A newly added function calling convention enables C++ to call Lua functions as if they were regular C++ functions.  This goes a long way to simplifying Lua for C++ users.

** A transparent C++ functor implementation is in place, allowing function callbacks to be global or static (as they are now), class member functions, or class member virtual functions.

** Direct registering of C++ functions with LuaPlus.  The registered C++ functions do not need to conform to a standard callback declaration.

** .NET wrapper.  The .NET version of LuaPlus opens up LuaPlus's features to any .NET based language.  This includes C#, Visual Basic, Python, Perl, and others.  The Managed C++ version of LuaPlus is nearly identical to its regular C++ counterpart, so transitioning is easy.

** Serialization of Lua tables.  Lua is a boon for data management.  With a much simpler syntax than XML, while providing equivalent and better data description facilities, a way is needed to write table data in text form.  LuaPlus offers this facility, and it does it in such a way that no Lua internal state is changed.

** Win32 DLL and LIB formats.  Through the DLL version, a module plug-in system is in place.

* Extra Tools:

** Debugger.  The Remote Lua Debugger all but eliminates the need to litter print() statements throughout script code.  It offers a view of the call stack, local variables, watch variables, syntax highlighting, has Visual C++ debugger style keystrokes, and much more.

** Visual C++ watch add-in to monitor data types.  When manipulating a LuaObject (one of the classes provided by the C++ interface), Visual C++ 6 and Visual Studio .NET show the contents of the LuaObject in the watch window.  The LuaWatchAddin makes no distinction between stack objects, ref'ed objects, up-values, or other indices.  In addition, if the index being shown is out of range, the LuaWatchAddin represents that.

** The Visual Studio .NET LuaPlus Debugger plug-in allows display of the Lua tables in tree form, local Lua variables, and the current Lua callstack.  Stepping through Lua code in the VS .NET environment is not possible at this time, but the Remote Lua Debugger may still be used.

* Lua Core Enhancements:

** 16-bit wide character string support.

** Tight integration of the extra string type was necessarily built into the code base.  Any reference to LUA_TSTRING in the Lua core code base was supplemented with an equivalent wide character LUA_TWSTRING.

** Direct support for opening Unicode files available.

** Ref'ed objects are treated no differently than a stack object.  Rather than dealing with low-level lua_getref() calls everywhere to load the ref'ed object onto the stack, the user can just "use" the object.  No special management is needed.

** Custom memory allocators and memory optimization support. For those working in embedded environments, better control over memory allocation is a must.