Skin.h

Includes:
<Foundation/Foundation.h>
"lobject.h"
"lapi.h"
"lauxlib.h"
"lualib.h"
"lua.h"
<assert.h>
<limits.h>
<dlfcn.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. Currently 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

LS_NSConversionOptions

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

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:.

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:.

LS_NSConversionOptions

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

typedef { 
    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,  LS_WithObjectWrapper = 1 << 15, LS_OW_ReadWrite = 
    1 << 16, LS_OW_WithArrayConversion = 1 << 17, 
};
Constants
LS_NSNone

(used by both methods) no options specified, use default behavior

LS_NSUnsignedLongLongPreserveBits

(used by pushNSObject:withOptions:) 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

(used by both methods) when a data 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 returning nil for the entire conversion. Not compatible with LS_NSIgnoreUnknownTypes.

LS_NSIgnoreUnknownTypes

(used by both methods) 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 returning nil for the entire conversion. Not compatible with LS_NSDescribeUnknownTypes.

LS_NSPreserveLuaStringExactly

(used by toNSObjectAtIndex:withOptions:) 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

(used by toNSObjectAtIndex:withOptions:) 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

(used by toNSObjectAtIndex:withOptions:) 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 default 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

(used by toNSObjectAtIndex:withOptions:) 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.

LS_WithObjectWrapper

(used by pushNSObject:withOptions:) Push NSArray or NSDictionary as userdata instead of table to lua stack. Meta-methods allow Lua to (mostly) use this as it would a table, but reduces overhead by not requiring data to be duplicated and inserted into Lua VM. Defaults to read-only (i.e. attempts to add or remove table elements in Lua will fail).

LS_OW_ReadWrite

(used by pushNSObject:withOptions:) When combined with LS_WithObjectWrapper, the virtual table can be modified from Lua by adding or removing elements (as long as doing so would not change the underlying NSObject type), and the corresponding NSObject will be updated to reflect the changes.

LS_OW_WithArrayConversion

(used by pushNSObject:withOptions:) When combined with LS_WithObjectWrapper and LS_OW_ReadWrite, modifying the virtual table in a way that would change the underlying NSObject type will cause it to be changed as necessary (e.g. adding a keyed element to an NSArray would change the underlying object to an NSDictionary; removing a keyed element from an NSDictionary that leaves only sequential integer keys starting at 1 will change the object to an NSArray.)

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);

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

Bit masks indicating valid argument types for use with checkArgs:

Log level definitions

Log level definitions for use with logAtLevel:withMessage:

LS_LOG_BREADCRUMB

Log level definitions for use with logAtLevel:withMessage:

LS_LOG_DEBUG

Log level definitions for use with logAtLevel:withMessage:

LS_LOG_ERROR

Log level definitions for use with logAtLevel:withMessage:

LS_LOG_INFO

Log level definitions for use with logAtLevel:withMessage:

LS_LOG_VERBOSE

Log level definitions for use with logAtLevel:withMessage:

LS_LOG_WARN

Log level definitions for use with logAtLevel:withMessage:

LS_TANY

Bit masks indicating valid argument types for use with checkArgs:

LS_TBOOLEAN

Bit masks indicating valid argument types for use with checkArgs:

LS_TBREAK

Bit masks indicating valid argument types for use with checkArgs:

LS_TFUNCTION

Bit masks indicating valid argument types for use with checkArgs:

LS_TINTEGER

Bit masks indicating valid argument types for use with checkArgs:

LS_TNIL

Bit masks indicating valid argument types for use with checkArgs:

LS_TNONE

Bit masks indicating valid argument types for use with checkArgs:

LS_TNUMBER

Bit masks indicating valid argument types for use with checkArgs:

LS_TOPTIONAL

Bit masks indicating valid argument types for use with checkArgs:

LS_TSTRING

Bit masks indicating valid argument types for use with checkArgs:

LS_TTABLE

Bit masks indicating valid argument types for use with checkArgs:

LS_TTYPEDTABLE

Bit masks indicating valid argument types for use with checkArgs:

LS_TUSERDATA

Bit masks indicating valid argument types for use with checkArgs:

LS_TVARARG

Bit masks indicating valid argument types for use with checkArgs:

LS_TWRAPPEDOBJECT

Bit masks indicating valid argument types for use with checkArgs:

Bit masks for Lua type checking

Bit masks indicating valid argument types for use with 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 
#define LS_TWRAPPEDOBJECT 1 << 14
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.

LS_TWRAPPEDOBJECT

maps to a userdata which represents a raw Objective-C object.

See Also

LS_TBREAK

LS_TOPTIONAL

LS_TNIL

LS_TBOOLEAN

LS_TNUMBER

LS_TSTRING

LS_TTABLE

LS_TFUNCTION

LS_TUSERDATA

LS_TNONE

LS_TANY

LS_TINTEGER

LS_TVARARG

LS_TTYPEDTABLE

LS_TWRAPPEDOBJECT

Log level definitions

Log level definitions for use with 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 occurred

See Also

LS_LOG_BREADCRUMB

LS_LOG_VERBOSE

LS_LOG_DEBUG

LS_LOG_INFO

LS_LOG_WARN

LS_LOG_ERROR

LS_LOG_BREADCRUMB

Log level definitions for use with logAtLevel:withMessage: 

#define LS_LOG_BREADCRUMB 6
Discussion

for messages that should be considered for recording in crash logs

See Also

Log level definitions

LS_LOG_DEBUG

Log level definitions for use with logAtLevel:withMessage: 

#define LS_LOG_DEBUG 4
Discussion

for messages that are usually only of interest during debugging

See Also

Log level definitions

LS_LOG_ERROR

Log level definitions for use with logAtLevel:withMessage: 

#define LS_LOG_ERROR 1
Discussion

for messages that indicate an error has occurred

See Also

Log level definitions

LS_LOG_INFO

Log level definitions for use with logAtLevel:withMessage: 

#define LS_LOG_INFO 3
Discussion

for messages that are informative

See Also

Log level definitions

LS_LOG_VERBOSE

Log level definitions for use with logAtLevel:withMessage: 

#define LS_LOG_VERBOSE 5
Discussion

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

See Also

Log level definitions

LS_LOG_WARN

Log level definitions for use with logAtLevel:withMessage: 

#define LS_LOG_WARN 2
Discussion

for messages that contain warnings

See Also

Log level definitions

LS_TANY

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TANY 1 << 10
Discussion

indicates that any Lua variable type is accepted

See Also

Bit masks for Lua type checking

LS_TBOOLEAN

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TBOOLEAN 1 << 3
Discussion

maps to LUA_TBOOLEAN

See Also

Bit masks for Lua type checking

LS_TBREAK

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TBREAK 1 << 0
Discussion

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

See Also

Bit masks for Lua type checking

LS_TFUNCTION

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TFUNCTION 1 << 7
Discussion

maps to LUA_TFUNCTION

See Also

Bit masks for Lua type checking

LS_TINTEGER

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TINTEGER 1 << 11
Discussion

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.

See Also

Bit masks for Lua type checking

LS_TNIL

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TNIL 1 << 2
Discussion

maps to LUA_TNIL

See Also

Bit masks for Lua type checking

LS_TNONE

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TNONE 1 << 9
Discussion

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.

See Also

Bit masks for Lua type checking

LS_TNUMBER

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TNUMBER 1 << 4
Discussion

maps to LUA_TNUMBER

See Also

Bit masks for Lua type checking

LS_TOPTIONAL

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TOPTIONAL 1 << 1
Discussion

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

See Also

Bit masks for Lua type checking

LS_TSTRING

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TSTRING 1 << 5
Discussion

maps to LUA_TSTRING

See Also

Bit masks for Lua type checking

LS_TTABLE

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TTABLE 1 << 6
Discussion

maps to LUA_TTABLE

See Also

Bit masks for Lua type checking

LS_TTYPEDTABLE

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TTYPEDTABLE 1 << 13
Discussion

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.

See Also

Bit masks for Lua type checking

LS_TUSERDATA

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TUSERDATA 1 << 8
Discussion

maps to LUA_TUSERDATA

See Also

Bit masks for Lua type checking

LS_TVARARG

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TVARARG 1 << 12
Discussion

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.

See Also

Bit masks for Lua type checking

LS_TWRAPPEDOBJECT

Bit masks indicating valid argument types for use with checkArgs: 

#define LS_TWRAPPEDOBJECT 1 << 14
Discussion

maps to a userdata which represents a raw Objective-C object.

See Also

Bit masks for Lua type checking

 

© The Hammerspoon Authors

Last Updated: Tuesday, March 14, 2023