LuaSkin

Introduction

Abstraction layer for common operations on Lua state objects

Discussion

LuaSkin was written for Hammerspoon (although it does not depend on any Hammerspoon functionality) to simplify our use of Lua. It includes a full, unmodified Lua distribution, and provides an Objective C class that is capable of performing common operations such as creating/destroying a lua_State object, providing shared access to the object, Lua function argument type checking and bi-directional conversion of Lua objects and NSObject objects (with loadable plugins for your own converters)

Converting NSObject objects into Lua variables

Group members:

Utility methods

Group members:

Registering module libraries with Lua

Group members:

Referencing Lua objects in Objective C

Group members:

Checking Lua arguments in Objective C functions

Group members:

Calling Lua functions from Objective C

Group members:

Lua state lifecycle

Group members:

Converting Lua variables into NSObjects

Group members:

Logging methods

Group members:

Methods

-canPushNSObject:

Pushes an NSObject to the lua stack

-checkArgs:

Ensures a Lua->C call has the right arguments

If the arguments are incorrect, this call will never return and the user will get a nice Lua traceback instead

-checkRefs:

Checks a list of Lua references for validity

-countNatIndex:

Returns the number of keys in the table at the specified index.

-createLuaState

Prepares the Lua environment in the LuaSkin object

WARNING:

This method should only ever be called after an explicit call to destroyLuaState. There is no need to call it when initialising a LuaSkin instance

-destroyLuaState

Destroys the Lua environment in the LuaSkin object

-getValidUTF8AtIndex:

Returns an NSString for the string at the specified index with invalid UTF8 byte sequences converted to the Unicode Invalid Character code.

WARNING:

This method uses luaL_tolstring so __tostring metamethods will be used if the index does not refer to a string or a number.

-growStack:withMessage:

Increases the size of Lua's stack

-isValidUTF8AtIndex:

Determines if the string in the lua stack is valid UTF8 or not

WARNING:

This method is used internally to determine if a string should be treated as an NSString or an NSData object. It is included as a public method because it has uses outside of this as well

WARNING:

This method uses lua_tolstring, which will convert a number on the stack to a string. As described in the Lua documentation, this will causes problems if you're using lua_next with the same index location

-logAtLevel:withMessage:

Log the specified message with at the specified level

-logBreadcrumb:

Log the specified message with LS_LOG_BREADCRUMB level

+logBreadcrumb:

Log the specified message from any thread with LS_LOG_BREADCRUMB level

-logDebug:

Log the specified message with LS_LOG_DEBUG level

+logDebug:

Log the specified message from any thread with LS_LOG_DEBUG level

-logError:

Log the specified message with LS_LOG_ERROR level

+logError:

Log the specified message from any thread with LS_LOG_ERROR level

-logInfo:

Log the specified message with LS_LOG_INFO level

+logInfo:

Log the specified message from any thread with LS_LOG_INFO level

-logKnownBug:

Log a known, but avoided issue via the log delegate, primarily to ensure it can be recorded in a crash reporting service

-logVerbose:

Log the specified message with LS_LOG_VERBOSE level

+logVerbose:

Log the specified message from any thread with LS_LOG_VERBOSE level

-logWarn:

Log the specified message with LS_LOG_WARN level

+logWarn:

Log the specified message from any thread with LS_LOG_WARN level

-luaObjectAtIndex:toClass:

Return an NSObject containing the best representation of the lua table at the specified index

WARNING:

This method uses registered converter functions provided by the Hammerspoon modules to convert the specified table into a recognizable NSObject. No converters are included within the LuaSkin. This method relies upon functions registered with the registerLuaObjectHelper:forClass: method for the conversions

-luaRef:

Stores a reference to the object at the top of the Lua stack, in the supplied table, and pops the object off the stack
This method is functionally analogous to luaL_ref(), it just takes care of pushing the supplied table ref onto the stack, and removes it afterwards

-luaRef:atIndex:

Stores a reference to the object at the specified position of the Lua stack, in the supplied table, without removing the object from the stack

-luaRef:forNSObject:

Stores a reference for an NSObject in the supplied table.

Use luaUnref:ref: to release an object retained by this method. Returns LUA_NOREF if canPushNSObject: returns NO.

-luaRelease:forNSObject:

Release a lua reference for an NSObject

-luaRetain:forNSObject:

Adds a lua reference to an NSObject to prevent garbage collection

-luaTypeAtIndex:

Returns the effective Lua type for the item at the specified stack index.

-luaUnref:ref:

Removes a reference from the supplied table

This method is functionally analogous to luaL_unref(), it just takes care of pushing the supplied table ref onto the Lua stack, and removes it afterwards

-maxNatIndex:

Returns the largest integer key in the table at the specified index.

-protectedCallAndError:nargs:nresults:

Calls protectedCallAndTraceback and will logError any failures

-protectedCallAndTraceback:nresults:

Calls lua_pcall() with debug.traceback() as the message handler

-pushLuaRef:ref:

Pushes a stored reference onto the Lua stack

This method is functionally analogous to lua_rawgeti(), it just takes care of pushing the supplied table ref onto the Lua stack, and removes it afterwards

-pushNSObject:

Pushes an NSObject to the lua stack

-pushNSObject:withOptions:

Pushes an NSObject to the lua stack with the specified options

-pushNSPoint:

Push an NSPoint onto the lua stack as a lua geometry object (table with x and y keys)

WARNING:

This is included as a separate method because NSPoint is a structure, not an NSObject

-pushNSRect:

Push an NSRect onto the lua stack as a lua geometry object (table with x,y,h, and w keys)

WARNING:

This is included as a separate method because NSRect is a structure, not an NSObject

-pushNSSize:

Push an NSSize onto the lua stack as a lua geometry object (table with w and h keys)

WARNING:

This is included as a separate method because NSSize is a structure, not an NSObject

-registerLibrary:functions:metaFunctions:

Defines a Lua library and creates a references table for the library

-registerLibrary:metaFunctions:

(DEPRECATED) Defines a Lua library and creates a references table for the library

-registerLibraryWithObject:functions:metaFunctions:objectFunctions:

Defines a Lua library that creates objects, which have methods

-registerLuaObjectHelper:forClass:

Register a luaObjectAtIndex:toClass: conversion helper function for the specified class

WARNING:

This method registers a converter function for use with the luaObjectAtIndex:toClass: method for converting lua data types into NSObjects

-registerLuaObjectHelper:forClass:withTableMapping:

Register a luaObjectAtIndex:toClass: conversion helper function for the specified class and record a mapping between a table type and the class

WARNING:

This method registers a converter function for use with the luaObjectAtIndex:toClass: method for converting lua data types into NSObjects. It builds on registerLuaObjectHelper:forClass: by also storing a mapping between the NSObject class and a Lua table with a type specification so objects of this type can be automatically converted with toNSObjectAtIndex: and toNSObjectAtIndex:withOptions: as well.

-registerLuaObjectHelper:forClass:withUserdataMapping:

Register a luaObjectAtIndex:toClass: conversion helper function for the specified class and record a mapping between a userdata type and the class

WARNING:

This method registers a converter function for use with the luaObjectAtIndex:toClass: method for converting lua data types into NSObjects. It builds on registerLuaObjectHelper:forClass: by also storing a mapping between the NSObject class and Lua userdata type so userdata objects of this type can be automatically converted with toNSObjectAtIndex: and toNSObjectAtIndex:withOptions: as well.

-registerLuaObjectHelper:forClass:withUserdataMapping:andTableMapping:

Register a luaObjectAtIndex:toClass: conversion helper function for the specified class and record a mapping between a userdata type and the class

WARNING:

This method registers a converter function for use with the luaObjectAtIndex:toClass: method for converting lua data types into NSObjects. It builds on registerLuaObjectHelper:forClass: by also storing a mapping between the NSObject class and Lua userdata type or a Lua table with a type specification so that objects of either type can be automatically converted with toNSObjectAtIndex: and toNSObjectAtIndex:withOptions: as well.

-registerObject:objectFunctions:

Defines a Lua object with methods

-registerPushNSHelper:forClass:

Register a helper function for converting an NSObject to its lua equivalent

WARNING:

This method allows registering a new NSObject class for conversion by allowing a module to register a helper function

-requireModule:

Loads a module and places its return value (usually a table of functions) on the stack

WARNING:

This method performs the equivalent of the lua command `require(...)` and places the return value (usually a table of functions) on the stack, or an error string on the stack if it was unable to load the specified module

-resetLuaState

Recreates the Lua environment in the LuaSkin object, from scratch

+shared

Returns the singleton LuaSkin.Skin object

WARNING:

This method is deprecated and may go away at some point. Use +(id)sharedWithState:(lua_State *)L instead.

+sharedWithDelegate:

Returns the singleton LuaSkin.Skin object and sets its delegate

+sharedWithState:

Returns the singleton LuaSkin.Skin object with the internal lua thread pointer set to the specified state.

-tableToPointAtIndex:

Convert a lua geometry object (table with x and y keys) into an NSPoint

WARNING:

This is included as a separate method because NSPoint is a structure, not an NSObject

-tableToRectAtIndex:

Convert a lua geometry object (table with x,y,h, and w keys) into an NSRect

WARNING:

This is included as a separate method because NSRect is a structure, not an NSObject

-tableToSizeAtIndex:

Convert a lua geometry object (table with h and w keys) into an NSSize

WARNING:

This is included as a separate method because NSSize is a structure, not an NSObject

-toNSObjectAtIndex:

Return an NSObject containing the best representation of the lua data structure at the specified index

-toNSObjectAtIndex:withOptions:

Return an NSObject containing the best representation of the lua data structure at the specified index

-tracebackWithTag:fromStackPos:

Returns a string containing the current stack top, the absolute index position of the stack top, and the output from luaL_traceback.

WARNING:

This method is primarily for debugging and may be removed in a future release.

canPushNSObject:

Pushes an NSObject to the lua stack

- (BOOL)canPushNSObject:(id)object; 

Parameters

Return Value

YES or NO indicating whether or not the LuaSkin instance can push the object onto the Lua stack.

Discussion

This method takes an NSObject and checks its class against registered classes to determine if the object can be represented in lua as a userdata.

checkArgs:

Ensures a Lua->C call has the right arguments

If the arguments are incorrect, this call will never return and the user will get a nice Lua traceback instead

- (void)checkArgs:(int)firstArg, ...; 

Parameters

Discussion

Each argument can use boolean OR's to allow multiple types to be accepted (e.g. LS_TNIL | LS_TBOOLEAN).

Each argument can be OR'd with LS_TOPTIONAL to indicate that the argument is optional.

LS_TUSERDATA arguments should be followed by a string containing the metatable tag name (e.g. "hs.screen" for objects from hs.screen).

WARNING:

checkRefs:

Checks a list of Lua references for validity

- (BOOL)checkRefs:(int)firstRef, ...; 

Parameters

Return Value

YES or NO indicating whether all of the supplied references are valid or not

Discussion

This compares each argument against LUA_REFNIL and LUA_NOREF. If any of the supplied arguments contain either of those values, this method returns NO. It does not guarantee that the references are valid within the Lua environment, simply that they have not been explicitly invalidated.

countNatIndex:

Returns the number of keys in the table at the specified index.

- (lua_Integer)countNatIndex:(int)idx; 

Parameters

Return Value

a lua_Integer value representing the number of keys in the table specified.

Discussion

This method returns a count of keys of any type in the specified table. Note that a table which contains an array has implicit integer indexes corresponding to the element's position in the array. Because of this, you can compare the result of this method to maxNatIndex: and if they are equal then it is safe to infer that the table represents a non-sparse array of elements.

createLuaState

Prepares the Lua environment in the LuaSkin object

WARNING:

- (void)createLuaState; 

destroyLuaState

Destroys the Lua environment in the LuaSkin object

- (void)destroyLuaState; 

getValidUTF8AtIndex:

Returns an NSString for the string at the specified index with invalid UTF8 byte sequences converted to the Unicode Invalid Character code.

WARNING:

- (NSString *)getValidUTF8AtIndex:(int)idx; 

Parameters

Return Value

The "safe" string as an NSString object.

growStack:withMessage:

Increases the size of Lua's stack

- (void)growStack:(int)slots withMessage:(const char *)message; 

Parameters

Discussion

This should be used before pushing items onto the stack. Each Lua->C transition is guaranteed to provide only 20 stack slots. It therefore seems wise to request more slots if we're going to be pushing things.

WARNING:

isValidUTF8AtIndex:

Determines if the string in the lua stack is valid UTF8 or not

WARNING:

WARNING:

- (BOOL)isValidUTF8AtIndex:(int)idx; 

Parameters

Return Value

YES if the string can be treated as a valid UTF8 string of characters or NO if it is not a string or if it contains invalid UTF8 byte sequences

logAtLevel:withMessage:

Log the specified message with at the specified level

- (void)logAtLevel:(int)level withMessage:(NSString *)theMessage; 

Parameters

Discussion

Logs the specified message at the specified level by invoking the delegate method logForLuaSkinAtLevel:withMessage:.

WARNING:

logBreadcrumb:

Log the specified message with LS_LOG_BREADCRUMB level

- (void)logBreadcrumb:(NSString *)theMessage; 

Parameters

Discussion

This method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_BREADCRUMB

logBreadcrumb:

Log the specified message from any thread with LS_LOG_BREADCRUMB level

+ (void)logBreadcrumb:(NSString *)theMessage; 

Parameters

Discussion

This class method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_BREADCRUMB, but is safe to use from any thread, not just the main application thread. If this method is invoked from a thread other than the main thread, it uses dispatch_async to submit the logging message to the main thread for proper handling by the delegate.

logDebug:

Log the specified message with LS_LOG_DEBUG level

- (void)logDebug:(NSString *)theMessage; 

Parameters

Discussion

This method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_DEBUG

logDebug:

Log the specified message from any thread with LS_LOG_DEBUG level

+ (void)logDebug:(NSString *)theMessage; 

Parameters

Discussion

This class method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_DEBUG, but is safe to use from any thread, not just the main application thread. If this method is invoked from a thread other than the main thread, it uses dispatch_async to submit the logging message to the main thread for proper handling by the delegate.

logError:

Log the specified message with LS_LOG_ERROR level

- (void)logError:(NSString *)theMessage; 

Parameters

Discussion

This method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_ERROR

logError:

Log the specified message from any thread with LS_LOG_ERROR level

+ (void)logError:(NSString *)theMessage; 

Parameters

Discussion

This class method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_ERROR, but is safe to use from any thread, not just the main application thread. If this method is invoked from a thread other than the main thread, it uses dispatch_async to submit the logging message to the main thread for proper handling by the delegate.

logInfo:

Log the specified message with LS_LOG_INFO level

- (void)logInfo:(NSString *)theMessage; 

Parameters

Discussion

This method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_INFO

logInfo:

Log the specified message from any thread with LS_LOG_INFO level

+ (void)logInfo:(NSString *)theMessage; 

Parameters

Discussion

This class method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_INFO, but is safe to use from any thread, not just the main application thread. If this method is invoked from a thread other than the main thread, it uses dispatch_async to submit the logging message to the main thread for proper handling by the delegate.

logKnownBug:

Log a known, but avoided issue via the log delegate, primarily to ensure it can be recorded in a crash reporting service

- (void)logKnownBug:(NSString *)message; 

Parameters

Discussion

If no delegate has been assigned, the message is logged to the system logs via NSLog.

logVerbose:

Log the specified message with LS_LOG_VERBOSE level

- (void)logVerbose:(NSString *)theMessage; 

Parameters

Discussion

This method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_VERBOSE

logVerbose:

Log the specified message from any thread with LS_LOG_VERBOSE level

+ (void)logVerbose:(NSString *)theMessage; 

Parameters

Discussion

This class method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_VERBOSE, but is safe to use from any thread, not just the main application thread. If this method is invoked from a thread other than the main thread, it uses dispatch_async to submit the logging message to the main thread for proper handling by the delegate.

logWarn:

Log the specified message with LS_LOG_WARN level

- (void)logWarn:(NSString *)theMessage; 

Parameters

Discussion

This method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_WARN

logWarn:

Log the specified message from any thread with LS_LOG_WARN level

+ (void)logWarn:(NSString *)theMessage; 

Parameters

Discussion

This class method is equivalent to invoking logAtLevel:withMessage: with level LS_LOG_WARN, but is safe to use from any thread, not just the main application thread. If this method is invoked from a thread other than the main thread, it uses dispatch_async to submit the logging message to the main thread for proper handling by the delegate.

luaObjectAtIndex:toClass:

Return an NSObject containing the best representation of the lua table at the specified index

WARNING:

- (id)luaObjectAtIndex:(int)idx toClass:(const char *)className; 

Parameters

Return Value

An NSObject of the appropriate type depending upon the data on the lua stack and the functions currently registered

luaRef:

Stores a reference to the object at the top of the Lua stack, in the supplied table, and pops the object off the stack
This method is functionally analogous to luaL_ref(), it just takes care of pushing the supplied table ref onto the stack, and removes it afterwards

- (int)luaRef:(int)refTable; 

Parameters

Return Value

An integer reference to the object that was at the top of the stack

luaRef:atIndex:

Stores a reference to the object at the specified position of the Lua stack, in the supplied table, without removing the object from the stack

- (int)luaRef:(int)refTable atIndex:(int)idx; 

Parameters

Return Value

An integer reference to the object at the specified stack position

luaRef:forNSObject:

Stores a reference for an NSObject in the supplied table.

Use luaUnref:ref: to release an object retained by this method. Returns LUA_NOREF if canPushNSObject: returns NO.

- (int)luaRef:(int)refTable forNSObject:(id)object; 

Parameters

Return Value

An integer reference to the object that was at the top of the stack

luaRelease:forNSObject:

Release a lua reference for an NSObject

- (void)luaRelease:(int)refTable forNSObject:(id)object; 

Parameters

Discussion

This method releases a reference to the object in the supplied table previously retained with luaRetain:forNSObject:. If the object has not previously been retained, this method has no effect.

luaRetain:forNSObject:

Adds a lua reference to an NSObject to prevent garbage collection

- (BOOL)luaRetain:(int)refTable forNSObject:(id)object; 

Parameters

Return Value

YES or NO indicating whether or not the object was retained in the specified reference table.

Discussion

This method stores a reference to the object in the supplied table if it is able to.

This can be used to prevent garbage collection of an object's userdata when the object must be retained whether or not the user has done so in lua. An object retained by this method can only be released through the use of luaRelease:forNSObject: or destroyLuaState:. Returns NO if canPushNSObject: returns NO.

luaTypeAtIndex:

Returns the effective Lua type for the item at the specified stack index.

- (int)luaTypeAtIndex:(int)idx; 

Parameters

Return Value

An integer which will be one of the following: LUA_TNIL, LUA_TNUMBER, LUA_TBOOLEAN, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA, LUA_TTHREAD, or LUA_TLIGHTUSERDATA.

Discussion

This method returns the Lua type for the item at the specified index.

At present, the only difference between this and the Lua API function `lua_type` is that a table with a __call metamethod is considered a function and will return LUA_TFUNCTION, since [LuaSkin protectedCallAndTraceback:nresults:] can accept such a table as the function to invoke.

luaUnref:ref:

Removes a reference from the supplied table

This method is functionally analogous to luaL_unref(), it just takes care of pushing the supplied table ref onto the Lua stack, and removes it afterwards

- (int)luaUnref:(int)refTable ref:(int)ref; 

Parameters

Return Value

An integer, always LUA_NOREF (you are advised to store this value in the variable containing the ref parameter, so it does not become a stale reference)

maxNatIndex:

Returns the largest integer key in the table at the specified index.

- (lua_Integer)maxNatIndex:(int)idx; 

Parameters

Return Value

a lua_Integer value containing the largest integer key in the table specified.

Discussion

If this number is equal to the number returned by countNatIndex:, then it is safe to infer that the table represents a non-sparse array of elements.

protectedCallAndError:nargs:nresults:

Calls protectedCallAndTraceback and will logError any failures

- (BOOL)protectedCallAndError:(NSString*)message nargs:(int)nargs 
        nresults:(int)nresults; 

Parameters

Return Value

NO if the Lua code threw an exception, otherwise YES

Discussion

]

protectedCallAndTraceback:nresults:

Calls lua_pcall() with debug.traceback() as the message handler

- (BOOL)protectedCallAndTraceback:(int)nargs nresults:(int)nresults; 

Parameters

Return Value

NO if the Lua code threw an exception, otherwise YES

Discussion

Here is some sample code:

 // First push a reference to the Lua function you want to call
 lua_rawgeti(L, LUA_REGISTRYINDEX, fnRef);

 // Then push the parameters for that function, in order
 lua_pushnumber(L, 1);

 // Finally, call protectedCallAndTraceback, telling it how
 // many arguments you pushed, and how many results you expect
 BOOL result = [luaSkin protectedCallAndTraceback:1 nresults:0];

 // The boolean return tells you whether the Lua code threw
 // an exception or not
 if (!result) handleSomeError();
 

WARNING:

pushLuaRef:ref:

Pushes a stored reference onto the Lua stack

This method is functionally analogous to lua_rawgeti(), it just takes care of pushing the supplied table ref onto the Lua stack, and removes it afterwards

- (int)pushLuaRef:(int)refTable ref:(int)ref; 

Parameters

Return Value

An integer containing the Lua type of the object pushed onto the stack

pushNSObject:

Pushes an NSObject to the lua stack

- (int)pushNSObject:(id)obj; 

Parameters

Return Value

The number of items pushed onto the lua stack - this will be 1 or 0, if conversion was not possible.

Discussion

This method is equivalent to invoking [LuaSkin pushNSObject:obj withOptions:LS_NSNone]. See pushNSObject:withOptions:.

The default classes are (in order): NSNull, NSNumber, NSValue, NSString, NSData, NSDate, NSArray, NSSet, NSOrderedSet, NSDictionary, NSURL, and NSObject.

pushNSObject:withOptions:

Pushes an NSObject to the lua stack with the specified options

- (int)pushNSObject:(id)obj withOptions:(NSUInteger)options; 

Parameters

Return Value

The number of items pushed onto the lua stack - this will be 1 or 0, if conversion was not possible.

Discussion

This method takes an NSObject and checks its class against registered classes and then against the built in defaults to determine the best way to represent it in Lua.

The default classes are (in order): NSNull, NSNumber, NSValue, NSString, NSData, NSDate, NSArray, NSSet, NSOrderedSet, NSDictionary, NSURL, and NSObject.

pushNSPoint:

Push an NSPoint onto the lua stack as a lua geometry object (table with x and y keys)

WARNING:

- (int)pushNSPoint:(NSPoint)thePoint; 

Parameters

Return Value

The number of items on the lua stack - this is always 1 but is returned to simplify its use in Hammerspoon modules

pushNSRect:

Push an NSRect onto the lua stack as a lua geometry object (table with x,y,h, and w keys)

WARNING:

- (int)pushNSRect:(NSRect)theRect; 

Parameters

Return Value

The number of items on the lua stack - this is always 1 but is returned to simplify its use in Hammerspoon modules

pushNSSize:

Push an NSSize onto the lua stack as a lua geometry object (table with w and h keys)

WARNING:

- (int)pushNSSize:(NSSize)theSize; 

Parameters

Return Value

The number of items on the lua stack - this is always 1 but is returned to simplify its use in Hammerspoon modules

registerLibrary:functions:metaFunctions:

Defines a Lua library and creates a references table for the library

- (LSRefTable)registerLibrary:(const char *)libraryName 
        functions:(const luaL_Reg *)functions metaFunctions:(const luaL_Reg *)metaFunctions; 

Parameters

Return Value

A Lua reference to the table created for this library to store its own references

Discussion

Lua libraries defined in C are simple mappings between Lua function names and C function pointers.

A library consists of a series of Lua functions that are exposed to the user, and (optionally) several special Lua functions that will be used by Lua itself. The most common of these is __gc which will be called when Lua is performing garbage collection for the library. These "special" functions are stored in the library's metatable. Other common metatable functions include __tostring and __index.

The mapping between Lua functions and C functions is done using an array of type luaL_Reg

Every C function pointed to in a luaL_Reg array must have the signature: static int someFunction(lua_State *L);

Here is some sample code:

 static const luaL_Reg myShinyLibrary[] = {
    {"doThing", function_doThing},
    {NULL, NULL} // Library arrays must always end with this
 };

 static const luaL_Reg myShinyMetaLibrary[] = {
    {"__gc", function_doLibraryCleanup},
    {NULL, NULL} // Library arrays must always end with this
 };

 [luaSkin registerLibrary:"myShinyLibrary" functions:myShinyLibrary metaFunctions:myShinyMetaLibrary];
 

registerLibrary:metaFunctions:

(DEPRECATED) Defines a Lua library and creates a references table for the library

- (LSRefTable)registerLibrary:(const luaL_Reg *)functions 
        metaFunctions:(const luaL_Reg *)metaFunctions __attribute__((deprecated("Please use the version of registerLibrary that takes the library name argument","
            registerLibrary:functions:metaFunctions:"))); 

Parameters

Return Value

An opaque reference to the table created for this library to store its own references

Discussion

Lua libraries defined in C are simple mappings between Lua function names and C function pointers.

NOTE: You should be using - (int)registerLibrary:(const char *)libraryName functions:(const luaL_Reg *)functions metaFunctions:(const luaL_Reg *)metaFunctions;

A library consists of a series of Lua functions that are exposed to the user, and (optionally) several special Lua functions that will be used by Lua itself. The most common of these is __gc which will be called when Lua is performing garbage collection for the library. These "special" functions are stored in the library's metatable. Other common metatable functions include __tostring and __index.

The mapping between Lua functions and C functions is done using an array of type luaL_Reg

Every C function pointed to in a luaL_Reg array must have the signature: static int someFunction(lua_State *L);

Here is some sample code:

 static const luaL_Reg myShinyLibrary[] = {
    {"doThing", function_doThing},
    {NULL, NULL} // Library arrays must always end with this
 };

 static const luaL_Reg myShinyMetaLibrary[] = {
    {"__gc", function_doLibraryCleanup},
    {NULL, NULL} // Library arrays must always end with this
 };

 [luaSkin registerLibrary:myShinyLibrary metaFunctions:myShinyMetaLibrary];
 

registerLibraryWithObject:functions:metaFunctions:objectFunctions:

Defines a Lua library that creates objects, which have methods

- (LSRefTable)registerLibraryWithObject:(const char *)libraryName 
        functions:(const luaL_Reg *)functions metaFunctions:(const luaL_Reg *)metaFunctions 
        objectFunctions:(const luaL_Reg *)objectFunctions; 

Parameters

Return Value

An opaque reference to the table created for this library to store its own references

Discussion

Here is some sample code:

 char *libraryName = "shinyLibrary";

 static const luaL_Reg myShinyLibrary[] = {
    {"newObject", function_createObject},
    {NULL, NULL} // Library arrays must always end with this
 };

 static const luaL_Reg myShinyMetaLibrary[] = {
    {"__gc", function_doLibraryCleanup},
    {NULL, NULL} // Library arrays must always end with this
 };

 static const luaL_Reg myShinyObjectLibrary[] = {
    {"doThing", function_objectDoThing},
    {"__gc", function_doObjectCleanup},
    {NULL, NULL} // Library arrays must always end with this
 };

 [luaSkin registerLibraryWithObject:libraryName functions:myShinyLibrary metaFunctions:myShinyMetaLibrary libraryObjectFunctions:myShinyObjectLibrary];
 

WARNING:

registerLuaObjectHelper:forClass:

Register a luaObjectAtIndex:toClass: conversion helper function for the specified class

WARNING:

- (BOOL)registerLuaObjectHelper:(luaObjectHelperFunction)helperFN 
        forClass:(const char *)className; 

Parameters

Return Value

True if registration was successful, or False if the function was not registered for some reason, most commonly because the class already has a registered conversion function.

registerLuaObjectHelper:forClass:withTableMapping:

Register a luaObjectAtIndex:toClass: conversion helper function for the specified class and record a mapping between a table type and the class

WARNING:

- (BOOL)registerLuaObjectHelper:(luaObjectHelperFunction)helperFN 
        forClass:(const char *)className withTableMapping:(const char *)tableTag; 

Parameters

Return Value

True if registration was successful, or False if the function was not registered for some reason, most commonly because the class already has a registered conversion function.

registerLuaObjectHelper:forClass:withUserdataMapping:

Register a luaObjectAtIndex:toClass: conversion helper function for the specified class and record a mapping between a userdata type and the class

WARNING:

- (BOOL)registerLuaObjectHelper:(luaObjectHelperFunction)helperFN 
        forClass:(const char *)className withUserdataMapping:(const char *)userdataTag; 

Parameters

Return Value

True if registration was successful, or False if the function was not registered for some reason, most commonly because the class already has a registered conversion function.

registerLuaObjectHelper:forClass:withUserdataMapping:andTableMapping:

Register a luaObjectAtIndex:toClass: conversion helper function for the specified class and record a mapping between a userdata type and the class

WARNING:

- (BOOL)registerLuaObjectHelper:(luaObjectHelperFunction)helperFN 
        forClass:(const char *)className withUserdataMapping:(const char *)userdataTag 
        andTableMapping:(const char *)tableTag; 

Parameters

Return Value

True if registration was successful, or False if the function was not registered for some reason, most commonly because the class already has a registered conversion function.

registerObject:objectFunctions:

Defines a Lua object with methods

- (void)registerObject:(const char *)objectName 
        objectFunctions:(const luaL_Reg *)objectFunctions; 

Parameters

Discussion

Here is some sample code:

 char *objectName = "shinyObject";

 static const luaL_Reg myShinyObject[] = {
    {"doThing", function_objectDoThing},
    {"__gc", function_objectCleanup},
    {NULL, NULL} // Function arrays must always end with this
 };

 [luaSkin registerObject:objectName objectFunctions:myShinyObject];
 

WARNING:

registerPushNSHelper:forClass:

Register a helper function for converting an NSObject to its lua equivalent

WARNING:

- (BOOL)registerPushNSHelper:(pushNSHelperFunction)helperFN 
        forClass:(const char *)className; 

Parameters

Return Value

True if registration was successful, or False if the function was not registered for some reason, most commonly because the class already has a registered conversion function.

requireModule:

Loads a module and places its return value (usually a table of functions) on the stack

WARNING:

- (BOOL)requireModule:(const char *)moduleName; 

Parameters

Return Value

YES if the module loaded successfully or NO if it does not

resetLuaState

Recreates the Lua environment in the LuaSkin object, from scratch

- (void)resetLuaState; 

shared

Returns the singleton LuaSkin.Skin object

WARNING:

+ (id)shared; 

Return Value

Shared instance of LuaSkin.Skin

sharedWithDelegate:

Returns the singleton LuaSkin.Skin object and sets its delegate

+ (id)sharedWithDelegate:(id)delegate; 

Parameters

Return Value

Shared instance of LuaSkinSkin

Discussion

It is only appropriate to use this class method when you are first bootstrapping your LuaSkin instance, and its only reason for existence is to ensure that the logging delegate is set early enough to capture any messages that might arise during the initial Lua instantiation. For all other purposes, use +(id)sharedWithState:(lua_State *)L.

WARNING:

sharedWithState:

Returns the singleton LuaSkin.Skin object with the internal lua thread pointer set to the specified state.

+ (id)sharedWithState:(lua_State *)L; 

Parameters

Return Value

Shared instance of LuaSkin.Skin

Discussion

This method will set the internal lua thread pointer to the specified state and should be invoked with the state passed into the C function defining a new lua function or method. For macOS delegates or other events which are triggered by the macOS rather than the lua engine executing a code block, pass in NULL for L.

tableToPointAtIndex:

Convert a lua geometry object (table with x and y keys) into an NSPoint

WARNING:

- (NSPoint)tableToPointAtIndex:(int)idx; 

Parameters

Return Value

An NSPoint created from the specified table

tableToRectAtIndex:

Convert a lua geometry object (table with x,y,h, and w keys) into an NSRect

WARNING:

- (NSRect)tableToRectAtIndex:(int)idx; 

Parameters

Return Value

An NSRect created from the specified table

tableToSizeAtIndex:

Convert a lua geometry object (table with h and w keys) into an NSSize

WARNING:

- (NSSize)tableToSizeAtIndex:(int)idx; 

Parameters

Return Value

An NSSize created from the specified table

toNSObjectAtIndex:

Return an NSObject containing the best representation of the lua data structure at the specified index

- (id)toNSObjectAtIndex:(int)idx; 

Parameters

Return Value

An NSObject of the appropriate type or nil if conversion was not possible.

Discussion

This method takes a lua object specified at the provided index and converts it into one of the basic NSObject types.

Basic Lua type to NSObject conversion

nil - nil if the index points directly to a nil lua object, or [NSNull null] if the nil is a member of a table

string - NSString

number - NSNumber numberWithInteger: or NSNumber numberWithDouble:

boolean - NSNumber numberWithBool:

table - NSArray if table is non-sparse with only integer keys starting at 1 or NSDictionary otherwise

Userdata types and typed tables (a lua table with a __luaSkinType key-value pair) will be converted to the appropriate Objective-C type if a module has registered a helper function for the specified type.

An empty table will be returned as an empty NSArray.

If the type is not in the above list, this method returns nil.

WARNING:

toNSObjectAtIndex:withOptions:

Return an NSObject containing the best representation of the lua data structure at the specified index

- (id)toNSObjectAtIndex:(int)idx withOptions:(NSUInteger)options; 

Parameters

Return Value

An NSObject of the appropriate type or nil if conversion was not possible.

Discussion

This method takes a lua object specified at the provided index and converts it into one of the basic NSObject types.

Basic Lua type to NSObject conversion rules:

nil - nil if the index points directly to a nil lua object, or [NSNull null] if the nil is a member of a table

string - NSString or NSData, depending upon options specified

number - NSNumber numberWithInteger: or NSNumber numberWithDouble:

boolean - NSNumber numberWithBool:

table - NSArray if table is non-sparse with only integer keys starting at 1 or NSDictionary otherwise

Userdata types and typed tables (a lua table with a __luaSkinType key-value pair) will be converted to the appropriate Objective-C type if a module has registered a helper function for the specified type.

An empty table will be returned as an empty NSArray.

If the type is not in the above list, this method will return nil for the entire conversion, or [NSNull null] or a description of the unrecognized type for the data or sub-component depending upon the specified options.

tracebackWithTag:fromStackPos:

Returns a string containing the current stack top, the absolute index position of the stack top, and the output from luaL_traceback.

WARNING:

- (NSString *)tracebackWithTag:(NSString *)theTag 
        fromStackPos:(int)level; 

Parameters

Return Value

an NSString object containing the output generated.

Properties

L

LuaSkin's internal Lua state object

mainLuaState

The lua state that LuaSkin was initialized with

L

LuaSkin's internal Lua state object

@property (atomic,
    readonly) lua_State *L; 

Discussion

Provides access to the raw Lua state object. Care should be taken when using this object, to ensure you are interacting with the Lua stack in a way that makes sense

mainLuaState

The lua state that LuaSkin was initialized with

@property (class,
    readonly,
    atomic) lua_State *mainLuaState; 

Discussion

Provides access to the raw Lua state object that was created when LuaSkin was initialized. This is the main lua thread where all callbacks should be run. Care should be taken when using this object, to ensure you are interacting with the Lua stack in a way that makes sense

Macro Definitions

LS_API

Entrypoint from Lua to C

This macro should be called at the start of every C function that is accessible from Lua. Its job is to create a LuaSkin object and validate the arguments expected to have been passed from Lua. It is a wrapper that performs:

  [LuaSkin sharedWithState:L];
  [skin checkArgs:__VA_ARGS__];
 

If the arguments are incorrect, this call will never return and the user will get a nice Lua traceback instead

LS_API

Entrypoint from Lua to C

This macro should be called at the start of every C function that is accessible from Lua. Its job is to create a LuaSkin object and validate the arguments expected to have been passed from Lua. It is a wrapper that performs:

  [LuaSkin sharedWithState:L];
  [skin checkArgs:__VA_ARGS__];
 

If the arguments are incorrect, this call will never return and the user will get a nice Lua traceback instead

#define LS_API(...) [LuaSkin sharedWithState:L]; [skin checkArgs:__VA_ARGS__]; 

Parameters

Discussion

Each argument can use boolean OR's to allow multiple types to be accepted (e.g. LS_TNIL | LS_TBOOLEAN).

Each argument can be OR'd with LS_TOPTIONAL to indicate that the argument is optional.

LS_TUSERDATA arguments should be followed by a string containing the metatable tag name (e.g. "hs.screen" for objects from hs.screen).

WARNING: