Skin.h

Includes:
"lobject.h"
"lapi.h"
"lauxlib.h"
"lualib.h"
"lua.h"

Introduction

An Objective-C framework that both wraps and abstracts Lua



Classes

LuaSkin

Abstraction layer for common operations on Lua state objects

Protocols

LuaSkinDelegate

Delegate method for passing control back to the parent environment for environment specific handling. Curerntly only offers support for passing log messages back to the parent environment for display or processing.



Functions

specMaskToString

convert a checkArgs: argument into a string


specMaskToString


convert a checkArgs: argument into a string

NSString *specMaskToString(
    int spec);  

Typedefs

luaObjectHelperFunction

a function which provides additional support for LuaSkin to convert a Lua object (usually, but not always, a table or userdata) into an NSObject. Helper functions are registered with registerLuaObjectHelper:forClass:, and are used as requested with luaObjectAtIndex:toClass:.

NS_OPTIONS

Conversion options for pushNSObject:withOptions: and toNSObjectAtIndex:withOptions:

pushNSHelperFunction

a function which provides additional support for LuaSkin to convert an NSObject into a Lua object. Helper functions are registered with registerPushNSHelper:forClass:, and are used as needed by toNSObjectAtIndex:.


luaObjectHelperFunction


a function which provides additional support for LuaSkin to convert a Lua object (usually, but not always, a table or userdata) into an NSObject. Helper functions are registered with registerLuaObjectHelper:forClass:, and are used as requested with luaObjectAtIndex:toClass:.

typedef id ( *luaObjectHelperFunction)(
    lua_State *L,
    int idx);  

NS_OPTIONS


Conversion options for pushNSObject:withOptions: and toNSObjectAtIndex:withOptions:

typedef NS_OPTIONS(NSUInteger, LS_NSConversionOptions) { 
    LS_NSNone = 0,  LS_NSUnsignedLongLongPreserveBits = 1 << 0, LS_NSDescribeUnknownTypes = 
    1 << 1, LS_NSIgnoreUnknownTypes = 1 << 5,  LS_NSPreserveLuaStringExactly = 
    1 << 2, LS_NSLuaStringAsDataOnly = 1 << 3, LS_NSAllowsSelfReference = 
    1 << 4, LS_NSRawTables = 1 << 6,  
};  
Constants
LS_NSNone

no options specified, use default beahvior

LS_NSUnsignedLongLongPreserveBits

convert NSNumber that contains an unsigned long long to a lua_Integer (long long) rather than preserve the numerical magnitude with lua_Number (double). Default is to preserve magnitude when the unsigned long long is greater than 0x7fffffffffffffff.

LS_NSDescribeUnknownTypes

when a date type or sub-type is unrecognized and does not match any defined converter, return a string describing the data (from [NSObject debugDescription] or luaL_tolstring, whichever is appropriate for the initial data type) instead of the default behavior of returing nil for the entire conversion. Not compatible with LS_NSDescribeUnknownTypes.

LS_NSIgnoreUnknownTypes

when a date type or sub-type is unrecognized and does not match any defined converter, return a nil placeholder (from [NSNull null] or lua_pushnil, whichever is appropriate for the initial data type) for the data or sub-component instead of the default behavior of returing nil for the entire conversion. Not compatible with LS_NSDescribeUnknownTypes.

LS_NSPreserveLuaStringExactly

If a Lua string contains character byte sequences which cannot be converted to a proper UTF8 Unicode character, return the string as an NSData object instead of the default lossy behavior of converting invalid sequences into the Unicode Invalid Character code. You should check your result to see if it is an NSString or an NSData object with the isKindOfClass: message if you select this option. Not compatible with LS_NSLuaStringAsDataOnly.

LS_NSLuaStringAsDataOnly

A lua string is always returned as an NSData object instead of the default lossy behavior of converting invalid sequences into the Unicode Invalid Character code. Not compatible with LS_NSPreserveLuaStringExactly.

LS_NSAllowsSelfReference

If a lua table contains a self reference (a table value which equals one of tables in which it is nested), allow the same self reference in the NSArray or NSDictionary object being created instead of the defualt behavior of returning nil for the entire conversion. Note that this option will create an object which likely cannot be fully collected by ARC without additional code due to strong internal references.

LS_NSRawTables

Always convert a Lua table to NSArray or NSDictionary, even if it contains a __luaSkinType field and a registered conversion function for the specified type exists.


pushNSHelperFunction


a function which provides additional support for LuaSkin to convert an NSObject into a Lua object. Helper functions are registered with registerPushNSHelper:forClass:, and are used as needed by toNSObjectAtIndex:.

typedef int ( *pushNSHelperFunction)(
    lua_State *L,
    id obj);  

Macro Definitions

Bit masks for Lua type checking with LuaSkin:checkArgs:
Log level definitions for logAtLevel:withMessage:
LS_LOG_BREADCRUMB
LS_LOG_DEBUG
LS_LOG_ERROR
LS_LOG_INFO
LS_LOG_VERBOSE
LS_LOG_WARN
LS_TANY
LS_TBOOLEAN
LS_TBREAK
LS_TFUNCTION
LS_TINTEGER
LS_TNIL
LS_TNONE
LS_TNUMBER
LS_TOPTIONAL
LS_TSTRING
LS_TTABLE
LS_TTYPEDTABLE
LS_TUSERDATA
LS_TVARARG

Bit masks for Lua type checking with LuaSkin:checkArgs:


 #define LS_TBREAK 1 << 0 
 #define LS_TOPTIONAL 1 << 1 
 #define LS_TNIL 1 << 2 
 #define LS_TBOOLEAN 1 << 3 
 #define LS_TNUMBER 1 << 4 
 #define LS_TSTRING 1 << 5 
 #define LS_TTABLE 1 << 6 
 #define LS_TFUNCTION 1 << 7 
 #define LS_TUSERDATA 1 << 8 
 #define LS_TNONE 1 << 9 
 #define LS_TANY 1 << 10 
 #define LS_TINTEGER 1 << 11 
 #define LS_TVARARG 1 << 12 
 #define LS_TTYPEDTABLE 1 << 13 
Included Defines
LS_TBREAK

The final value in all checkArgs calls, signals the end of the argument list

LS_TOPTIONAL

Can be OR'd with any argument to indicate that it does not have to be present

LS_TNIL

maps to LUA_TNIL

LS_TBOOLEAN

maps to LUA_TBOOLEAN

LS_TNUMBER

maps to LUA_TNUMBER

LS_TSTRING

maps to LUA_TSTRING

LS_TTABLE

maps to LUA_TTABLE

LS_TFUNCTION

maps to LUA_TFUNCTION

LS_TUSERDATA

maps to LUA_TUSERDATA

LS_TNONE

maps to LUA_TNONE. Deprecated, as this serves no real use in checkArgs except to provide parity with Lua's LUA_TNONE, which is handled by optional argument tagging or as an argument count error.

LS_TANY

indicates that any Lua variable type is accepted

LS_TINTEGER

Can be OR'd with LS_TNUMBER to specify that the number must be an integer. This option is ignored if paired with other types.

LS_TVARARG

Can be OR'd with LS_TBREAK to indicate that any additional arguments on the stack after this location are to be ignored by checkArgs . It is the responsibility of the module function to check and use or ignore any additional arguments.

LS_TTYPEDTABLE

maps to LUA_TTABLE, but like LS_TUSERDATA, expects a string argument following which specifies the specific value expected in the __luaSkinType field of the table.


Log level definitions for logAtLevel:withMessage:


 #define LS_LOG_BREADCRUMB 6 
 #define LS_LOG_VERBOSE 5 
 #define LS_LOG_DEBUG 4 
 #define LS_LOG_INFO 3 
 #define LS_LOG_WARN 2 
 #define LS_LOG_ERROR 1 
Included Defines
LS_LOG_BREADCRUMB

for messages that should be considered for recording in crash logs

LS_LOG_VERBOSE

for messages that contain excessive detail that is usually only of interest during debugging

LS_LOG_DEBUG

for messages that are usually only of interest during debugging

LS_LOG_INFO

for messages that are informative

LS_LOG_WARN

for messages that contain warnings

LS_LOG_ERROR

for messages that indicate an error has occured