LuaState (a Lua Wrapper) 4.1 Alpha Distribution

LuaState (a Lua Wrapper) 4.1 Alpha Distribution

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

Overview

Warning: The following distribution contains modified Lua code.? It is not an official distribution of Lua as the authors intended it.? 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.

The intent of this package is not to masquerade as an official Lua interpreter.? Any references to Lua in this document refer specifically to the modified Lua code contained herein, unless otherwise noted.? Only additions have been made to Lua.

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.

API documentation is here.

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.

Unicode strings can be entered into Lua script using the C approach to wide character strings.

L"Wide characters"

By inserting an L in front of the quote, the Lua lexer creates a wide character representation of the above string.? If the string was entered as a regular Lua string, the Unicode equivalent would be simulated as follows:

"W\000i\000d\000e\000 \000c\000h\000a\000r\000a\000c\000t\000e\000r\000s\000\000\000"

In the event it is necessary to insert Unicode character codes in the wide character string, an additional property of the L"" approach may be used.? 16-bit characters may be entered using hexadecimal notation, in the same way as C:

L"Wide characters: \x3042\x3043"

The standard Lua libraries have been upgraded to accept and operate on Unicode strings.? Below is a brief list of added functionality.

• LUA_TUSTRING type added.? Mirrors LUA_TSTRING.
• print() has been upgraded to take Unicode strings as input.
• tonumber() can take a Unicode string as a parameter.
• If tostring() receives a Unicode string as input, it converts it to ANSI and returns it.
• toustring() added.? If toustring() receives an ANSI string as input, it converts it to Unicode and returns it.
• read() can read Unicode files/strings if the input string is Unicode.? The file must be opened in binary mode.
• write() can write Unicode strings.
• The following lstrlib.c functions have been added and upgraded to Unicode.? All behavior corresponds to the ANSI equivalents.
  • ustrlen().? Mirrors strlen().
  • ustrsub().? Mirrors strsub().
  • ustrlower().? Mirrors strlower().
  • ustrupper().? Mirrors strupper().
  • ustrrep().? Mirrors strrep().
  • ustrbyte().? Mirrors strbyte().
  • ustrchar().? Mirrors strchar().
  • uformat().? Mirrors format().
  • ustrfind().? Mirrors strfind().
  • ugsub().? Mirrors gsub().
• The following public Lua functions have been added or upgraded and mirror their ANSI counterparts:
  • lua_isustring() added.? Mirrors lua_isstring().
  • lua_toustring() added.? Mirrors lua_tostring().
  • lua_pushlustring() added.? Mirrors lua_pushlstring().
  • lua_pushustring() added.? Mirrors lua_pushustring().
  • lua_pushuliteral() added.? Mirrors lua_pushliteral().
  • lua_strlen() will properly report the length of a Unicode string.
• The following private Lua functions have been added and mirror their ANSI counterparts:
  • Addition of luaL_check_lustr().? Mirrors luaL_checklstr().
  • luaL_check_ustring() added.? Mirrors luaL_check_string().
  • luaL_addusize() added.? Mirrors luaL_addsize().
  • luaL_addlustring().? Mirrors luaL_addlstring().
  • luaL_addustring().? Mirrors luaL_addstring().
  • l_us() define added.? Mirrors l_s().
  • l_uc() define added.? Mirrors l_c().
  • LUA_NUMBER_USCAN.? Mirrors LUA_NUMBER_SCAN.
  • LUA_NUMBER_UFMT.? Mirrors LUA_NUMBER_FMT.
  • luaL_Buffer can now distinguish whether it is in double byte or single byte form.
  • Addition of luaL_putwchar().? Mirrors luaL_putchar().
  • luaL_buffinit() takes an additional parameter.
  • lua_number2ustr() added.

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.

For purposes of better memory tracking, the realloc() callback allows a void pointer of user data, an allocation name, and allocation flags to be passed along.? All of these arguments are optional, but they are available if the memory allocation callback needs them.

The only allocation flag available is LUA_ALLOC_TEMP.? A memory manager could react to the LUA_ALLOC_TEMP flag, for instance, by allocating the code for the main function of a Lua file at the top of the heap.? If all other Lua allocations happen at the bottom of the heap, no holes will be left in memory when the LUA_ALLOC_TEMP flagged allocation is garbage collection.

The callbacks look like:

				static
				void* luaHelper_ReallocFunction(void* ptr, intsize, void* data, constchar* allocName, unsignedintallocFlags)
{
    returnrealloc(ptr, size);
}

				static
				void
				luaHelper_FreeFunction(void* ptr, void* data)
{
    free(ptr);
}

The allocation functions must be assigned before a Lua global state is created, in a fashion similar to below.? It is good practice to restore the previous realloc() and free() callbacks.

				lua_ReallocFunction
				oldReallocFunc;
lua_FreeFunctionoldFreeFunc;
void* oldData;
lua_getdefaultmemoryfunctions(&oldReallocFunc, &oldFreeFunc, &oldData);
lua_setdefaultmemoryfunctions(luaHelper_ReallocFunction, luaHelper_FreeFunction, NULL);
lua_State* state = lua_open(0);
lua_setdefaultmemoryfunctions(oldReallocFunc, oldFreeFunc, oldData);

Memory Optimizations

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

• lua_setminimumstringtablesize(int numstrings) will ensure the global string table is always of the minimum size specified by numstrings.? When garbage collection occurs, the string table will never shrink below numstrings.? An application can determine the maximum number of strings it will use and ensure the space is reserved in advance, so as to avoid fragmentation when the string table is resized.
• lua_setdefaulttagtablesize(int numtags) will create a hash table of numtags size for the tag table.
• lua_setminimumglobaltablesize(int numentries) ensures the globals table is capable of at least holding numentries elements without resizing to avoid fragmenting the heap.
• lua_setminimumauxspace(int size) creates a minimum auxiliary space buffer of size bytes.? Auxiliary space is automatically allocated with the allocation flag LUA_ALLOC_TEMP.? An application might use this to put auxiliary space at the top of a heap or in some other location, so later freeing of it doesn't cause fragmentation issues.
• lua_setmainfunctionallocflags(flags) sets the allocation flags to be used when reading in the main function of a chunk.? The user could pass in LUA_ALLOC_TEMP as the main function allocation flag.
• lua_newtablesize(lua_State* L, int size) is an enhanced version of lua_newtable() that creates a hash table of size so as to avoid reallocations.
• luaM_setname() macro added and is used internally to name groups of allocations.? The name is passed into the realloc() callback function and may be used to better categorize allocations.
• lua_loadfile() has been optimized to not push temporary strings to the Lua stack which immediately can be garbage collected.? This is another optimization that avoids "holes" in a memory heap.
• Tables can be created in the form:
  • table = { &100 1, 2, 3, 4, 5, 6 } where the &100 creates a table hash table of size 100.? The &100 may, of course, be any value.

Multithreading

Multithreading is built into the LuaState distribution by default.? The function lua_setlockfunctions() can be used to set up the multithreading.

Example:

				static
				void
				LSLock(void* data)
{
    CRITICAL_SECTION* cs = (CRITICAL_SECTION*)data;
    ::EnterCriticalSection(cs);
}

staticvoidLSUnlock(void* data)
{
    CRITICAL_SECTION* cs = (CRITICAL_SECTION*)data;
    ::LeaveCriticalSection(cs);
}
lua_State* m_state = lua_open(stackSize);
CRITICAL_SECTION* cs = newCRITICAL_SECTION;
::InitializeCriticalSection(cs);
lua_setlockfunctions(m_state, LSLock, LSUnlock, cs);

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.

Other Optimizations

• lua_gettop() has been inlined in lua.h.? This is because LuaState uses lua_gettop() a lot, but most C++ optimizers will optimize the calls out.
• TObject 's structure format has been manipulated to fit in less memory.? This works great in an environment where a lot of tags are not created.? Otherwise, the default implementation of TObject is better.

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.

Additionally, ANSI strings can use the hexadecimal character notation to insert bytes into the string:

str = "Hel\x80o"

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.? There are some advantages offered by the pointer type over the user data type:

1. Handing off a pointer to Lua is "free."? For user data, there is a memory cost associated with creating a user data object.? For simple pointer passing, the pointer type is a much better alternative.
2. Since the mantissa of a double is large enough to hold a 32-bit pointer without data loss, a Lua double could be used to hand off pointers.? The pointer interface is much cleaner than the double one and far more portable.

A pointer is represented by the Lua type, LUA_TPOINTER.? The following functions are available for pointer access and mirror their Lua type counterparts:

• lua_ispointer()
• lua_getpointer() -- Since lua_topointer() is in use.
• lua_pushpointer()

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.

Every data type has methods, even numbers.? It is possible to write code that looks like:

print(4->sqrt())
str = "Hello"
print(str->len())

For the majority of cases, the use of tag methods can more or less be forgotten.

The default method tables have been put into global names for convenience. They are named like the type but with a capital first letter (Nil, Number, String, UString, Function, Table, Userdata).

Method tables may be accessed from within Lua using the methods() function.

				table
				
				
				
						=
				
				
				
				
						{}


				
				-- Save the old methods.

				tableMethods
				
				
				
						=
				
				
				
				methods(table)

newMethods
				
				
				
						=
{

						
						doNothing
				
				
				
						=
				
				
				
				
						function
						(
				
				self)
    
				
						end

						}


				
				-- Set the new methods.

				methods(table,
				
				
				newMethods)
table->doNothing()
		

In C, methods may be retrieved using the following functions:

				LUA_API
				void
				lua_getmethods(lua_State *L, intindex);
LUA_APIvoidlua_getdefaultmethods(lua_State *L, inttype);
LUA_APIvoidlua_setmethods(lua_State *L, intindex);

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)
		

• fileName - The name of the file to write to disk.
• filePtr - A pointer from the Lua function openfile().
• objectName - The name of the initial Lua table to write to disk.
• valueToWrite - The Lua table to write.
• indentLevel - The number of tabs to indent each line.? Passing in -1 will cause special formatting to occur that assumes the globals() table is being written.
• writeAll - If 1, writes all Lua objects out, including function and user data information.
• alphabetical - If 1, each table written is sorted.
• maxIndentLevel - May be nil.? The maximum number of nested tables allowed in the write.? If this value is exceeded, then no carriage returns are inserted.

The C++ functionality is very similar in form.

Standard Unified Method Callbacks

The basic types have the following unified method callbacks applied to them.

				Table
				
				
				
						=
{

						
						
				
				
						function
				
				
				
				foreach(self,
				
				
				func)

				
						function
				
				
				
				foreachi(self,
				
				
				func)

				
						function
				
				
				
				next(self,
				
				
				
						[index])

				
						function
				
				
				
				rawget(self,
				
				
				index)

				
						function
				
				
				
				rawset(self,
				
				
				index,
				
				
				value)

				
						function
				
				
				
				getn(self)

				
						function
				
				
				
				sort(self
				
				
				
						[,
				
				
				
				comp])

				
						function
				
				
				
				insert(self
				
				
				
						[,
				
				
				
				pos]
				
				
				
						,
				
				
				
				value)
				
				
				-- tinsert

				
				
				
						function
				
				
				
				remove(self
				
				
				
						[,
				
				
				
				pos])
				
				
				-- tremove

				
						    function
				
				
				
				unpack(self)
}

File
				
				
				
						=
{

						
						
				
				
						function
				
				
				
				close(self)
				
				
				-- closefile

				
				
				
						function
				
				
				
				flush(self)
				
				
				-- flush

				
						    function
				
				
				
				open(filename,
				
				
				mode)
				
				
				-- openfile

				
						    function
				
				
				
				read([self,]
				
				
				format1,
				
				
				
						...)
				
				
				
				-- read

				
						    function
				
				
				
				seek(self
				
				
				
						[,
				
				
				
				whence]
				
				
				
						[,
				
				
				
				offset])
				
				
				-- seek

				
						    function
				
				
				
				write([self,]
				
				
				value1,
				
				
				
						...)
				
				
				
				-- write

				
						    function
				
				
				
				execute(command)
				
				
				-- execute

				
						    function
				
				
				
				remove(filename)
				
				
				-- remove

				
						    function
				
				
				
				rename(name1,
				
				
				name2)
				
				
				-- rename

				
						    function
				
				
				
				tmpname()
				
				
				-- tmpname

				    stdin
    stdout
    stderr
}

String=
{
functionlen(self)-- strlen
functionsub(self,i[,j])-- strsub
    functionlower(self)-- strlower
    functionupper(self)-- strupper
    functionchar(i1,i2,...)-- strchar
    functionrep(self,n)-- strrep
    functionbyte(self[,i])-- strbyte
    functionformat(formatstring,e1,e2,...)-- format
    functionfind(self,pattern[,init[,plain]])-- strfind
    functiongsub(self,pat,repl[,n])-- gsub
}

UString
				
				
				
						=
{

						
						
				
				
						function
				
				
				
				len(self)
				
				
				-- ustrlen

				
				
				
						function
				
				
				
				sub(self,
				
				
				i
				
				
				
						[,
				
				
				
				j])
				
				
				-- ustrsub

				
						    function
				
				
				
				lower(self)
				
				
				-- ustrlower

				
						    function
				
				
				
				upper(self)
				
				
				-- ustrupper

				
						    function
				
				
				
				char(i1,
				
				
				i2,
				
				
				
						...)
				
				
				
				-- ustrchar

				
						    function
				
				
				
				rep(self,
				
				
				n)
				
				
				-- ustrrep

				
						    function
				
				
				
				byte(self
				
				
				
						[,
				
				
				
				i])
				
				
				-- ustrbyte

				
						    function
				
				
				
				format(formatstring,
				
				
				e1,
				
				
				e2,
				
				
				
						...)
				
				
				
				-- uformat

				
						    function
				
				
				
				find(self,
				
				
				pattern
				
				
				
						[,
				
				
				
				init
				
				
				
						[,
				
				
				
				plain]])
				
				
				-- ustrfind

				
						    function
				
				
				
				gsub(self,
				
				
				pat,
				
				
				repl
				
				
				
						[,
				
				
				
				n])
				
				
				-- ugsub

				
						}

Number
				
				
				
						=
{

						
						
				
				
						function
				
				
				
				abs()

				
						    function
				
				
				
				sin()

				
						    function
				
				
				
				cos()

				
						    function
				
				
				
				tan()

				
						    function
				
				
				
				asin()

				
						    function
				
				
				
				acos()

				
						    function
				
				
				
				atan()

				
						    function
				
				
				
				atan2()

				
						    function
				
				
				
				ceil()

				
						    function
				
				
				
				floor()

				
						    function
				
				
				
				mod()

				
						    function
				
				
				
				frexp()

				
						    function
				
				
				
				ldexp()

				
						    function
				
				
				
				sqrt()

				
						    function
				
				
				
				min()

				
						    function
				
				
				
				max()

				
						    function
				
				
				
				log()

				
						    function
				
				
				
				log10()

				
						    function
				
				
				
				exp()

				
						    function
				
				
				
				deg()

				
				
				
						function
				
				
				
				rad()

				
				
				
						function
				
				
				
				random()

				
				
				
						function
				
				
				
				randomseed()
}
		

Bonus Functions

				FileFind
				
				
				
						=
{

						
						
				
				-- Returns a handle representing the first file matching fileName.

				
				
				
						function
				
				
				
				First(fileName)


				
				
				-- Retrieves the next file matching fileName.

				
						    function
				
				
				
				Next(self)


				
						
						
				
				-- Closes the file search.

				
						
						
				
				
						function
				
				
				
				Close(self)


				
						
						
				
				-- Gets the file name of the currently matched file.

				
						
						
				
				
						function
				
				
				
				GetFileName(self)


				
						
						
				
				-- Determines if the currently matched file is a directory.

				
						
						
				
				
						function
				
				
				
				IsDirectory(self)
}


				-- Added to File:

				File
				
				
				
						=
{

				
				
						
						
				
				-- Returns the size of fileName.

				
						    function
				
				
				
				GetFileSize(fileName)


				
						
						
				
				-- Returns as two numbers the last write time for fileName.

				
						    function
				
				
				
				GetWriteTime(fileName)
				
						
						
				
				-- Sets the write time for fileName.

				
						    function
				
				
				
				SetWriteTime(fileName,
				
				
				timeLo,
				
				
				timeHi)


				
				
				-- Same as the C function _access.

				
						    function
				
				
				
				access(fileName,
				
				
				type)
}


				-- Returns a new table with a hash table of size.

				
						function
				
				
				
				NewTableSize(size)


				-- Copies a non-cyclic table recursively.

				
						function
				
				
				
				CopyTable(tableToCopy)


				-- Looks up a table entry by string name: Table1.Table2.3.Value2

				
						function
				
				
				
				FullLookup(table,
				
				
				lookupStr)


				-- Processes all the files matching wildcard in the directory [path] and calls func(path, name) on each one.

				
						function
				
				
				
				DirProcessFiles(path,
				
				
				wildcard,
				
				
				func)


				-- Recursively processes all the files in the directory [path], optionally matching [ext] and calls func(path, name) on each one.

				
						function
				
				
				
				DirProcessFilesRecursive(path,
				
				
				func,
				
				
				ext)
		

posted on 2006-08-20 13:26 楊粼波 閱讀(2267) 評(píng)論(0)  編輯 收藏 引用 所屬分類(lèi): 腳本引擎