LuaSkin

Superclass:
NSObject
Declared In:

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)



Groups

Referencing Lua objects in Objective C

Group members:

-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

-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

-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

 

Checking Lua arguments in Objective C functions

Group members:

-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

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

 

Converting NSObject objects into Lua variables

Group members:

-canPushNSObject:

Pushes an NSObject to the lua stack

-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

-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

 

Registering module libraries with Lua

Group members:

-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

-registerObject:objectFunctions:

Defines a Lua object with methods

 

Utility methods

Group members:

-countNatIndex:

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

-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

-maxNatIndex:

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

-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

 

Lua state lifecycle

Group members:

-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

-resetLuaState

Recreates the Lua environment in the LuaSkin object, from scratch

 

Calling Lua functions from Objective C

Group members:

-protectedCallAndError:nargs:nresults:

Calls protectedCallAndTraceback and will logError any failures

-protectedCallAndTraceback:nresults:

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

 

Logging methods

Group members:

-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

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

 

Converting Lua variables into NSObjects

Group members:

-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

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

-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


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
object

an NSObject

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
firstArg

- An integer that defines the first acceptable Lua argument type. Possible values are defined here . Followed by zero or more integers of the same possible values. The final value MUST be LS_TBREAK

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:

The final argument MUST be LS_TBREAK, to signal the end of the list


checkRefs:


Checks a list of Lua references for validity

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

- An integer containing a Lua reference. Followed by zero or more integers containing other Lua references. The final value MUST be LS_RBREAK.

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
idx

the index on lua stack which contains the lua table

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:

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

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

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

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

the index on lua stack which contains the lua object

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
slots

The number of additional slots to add to the stack

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:

If the stack size cannot be increased, a luaL_error() will be thrown


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

- (BOOL)isValidUTF8AtIndex:(int)idx; 
Parameters
idx

the index on lua stack which contains the string to check

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
level

The message log level as an integer. Predefined levels are defined and used within LuaSkin itself as (in decreasing level of severity) LS_LOG_ERROR, LS_LOG_WARN, LS_LOG_INFO, LS_LOG_DEBUG, and LS_LOG_VERBOSE.

theMessage

the message to log

Discussion

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

WARNING:

If no delegate has been defined, messages are logged to the system console via NSLog.


logBreadcrumb:


Log the specified message with LS_LOG_BREADCRUMB level

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

the message to log

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
theMessage

the message to log

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
theMessage

the message to log

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
theMessage

the message to log

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
theMessage

the message to log

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
theMessage

the message to log

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
theMessage

the message to log

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
theMessage

the message to log

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
message

The message to log

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
theMessage

the message to log

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
theMessage

the message to log

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
theMessage

the message to log

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
theMessage

the message to log

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:

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

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

the index on lua stack which contains the table to convert

className

a C string containing the class name of the NSObject type to return. If no converter function is currently registered for this type, nil is returned

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
refTable

- An opaque reference to a table, (e.g. the result of a previous luaRef on a table object or the result of the module's registration through registerLibrary:metaFunctions: or registerLibraryWithObject:functions:metaFunctions:objectFunctions:)

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
refTable

- An opaque reference to a table, (e.g. the result of a previous luaRef on a table object or the result of the module's registration through registerLibrary:metaFunctions: or registerLibraryWithObject:functions:metaFunctions:objectFunctions:)

idx

- An integer stack position

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
refTable

- An opaque reference to a table, (e.g. the result of a previous luaRef on a table object or the result of the module's registration through registerLibrary:metaFunctions: or registerLibraryWithObject:functions:metaFunctions:objectFunctions:)

object

an NSObject

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
refTable

- An integer reference to a table, (e.g. the result of a previous luaRef on a table object or the result of the module's registration through registerLibrary:metaFunctions: or registerLibraryWithObject:functions:metaFunctions:objectFunctions:)

object

an NSObject

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
refTable

- An integer reference to a table, (e.g. the result of a previous luaRef on a table object or the result of the module's registration through registerLibrary:metaFunctions: or registerLibraryWithObject:functions:metaFunctions:objectFunctions:)

object

an NSObject

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
idx

the index on lua stack which contains the data to return a type for

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
refTable

- An opaque reference to a table, (e.g. the result of a previous luaRef on a table object or the result of the module's registration through registerLibrary:metaFunctions: or registerLibraryWithObject:functions:metaFunctions:objectFunctions:)

ref

- An integer reference for an object that should be removed from the refTable table

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
idx

the index on lua stack which contains the lua table

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
nargs

An integer specifying how many function arguments you have pushed onto the stack

nresults

An integer specifying how many return values the Lua function will push onto the stack

message

An NSString message to include in the error log

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
nargs

An integer specifying how many function arguments you have pushed onto the stack

nresults

An integer specifying how many return values the Lua function will push onto the stack

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:

You are strongly advised to check the return code of this method - if it returns NO there will be an error message left on the Lua stack, which you should pop


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
refTable

- An opaque reference to a table, (e.g. the result of a previous luaRef on a table object or the result of the module's registration through registerLibrary:metaFunctions: or registerLibraryWithObject:functions:metaFunctions:objectFunctions:)

ref

- An integer reference for an object that should be pushed onto the stack

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
obj

an NSObject

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
obj

an NSObject

options

options for the conversion made by using the bitwise OR operator with members of LS_NSConversionOptions.

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:

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

- (int)pushNSPoint:(NSPoint)thePoint; 
Parameters
thePoint

the point to push onto the lua stack

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:

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

- (int)pushNSRect:(NSRect)theRect; 
Parameters
theRect

the rectangle to push onto the lua stack

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:

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

- (int)pushNSSize:(NSSize)theSize; 
Parameters
theSize

the point to push onto the lua stack

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
libraryName

- A C string containing the name of the library

functions

- A static array of mappings between Lua function names and C function pointers. This provides the public API of the Lua library

metaFunctions

- A static array of mappings between special meta Lua function names (such as __gc) and C function pointers

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
functions

- A static array of mappings between Lua function names and C function pointers. This provides the public API of the Lua library

metaFunctions

- A static array of mappings between special meta Lua function names (such as __gc) and C function pointers

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
libraryName

- A C string containing the name of this library

functions

- A static array of mappings between Lua function names and C function pointers. This provides the public API of the Lua library

metaFunctions

- A static array of mappings between special meta Lua function names (such as "__gc") and C function pointers

objectFunctions

- A static array of mappings between Lua object method names and C function pointers. This provides the public API of objects created by this library. Note that this object is also used as the metatable, so special functions (e.g. "__gc") should be included here

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:

Every C function pointer must point to a function of the form: static int someFunction(lua_State *L);


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

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

a function of the type luaObjectHelperFunction

className

a C string containing the class name of the NSObject type this function can convert

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:

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.

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

a function of the type luaObjectHelperFunction

className

a C string containing the class name of the NSObject type this function can convert

tableTag

a C string containing the Lua table type specification that can be converted to an NSObject

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:

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.

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

a function of the type luaObjectHelperFunction

className

a C string containing the class name of the NSObject type this function can convert

userdataTag

a C string containing the Lua userdata type that can be converted to an NSObject

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:

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.

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

a function of the type luaObjectHelperFunction

className

a C string containing the class name of the NSObject type this function can convert

userdataTag

a C string containing the Lua userdata type that can be converted to an NSObject

tableTag

a C string containing the Lua table type specification that can be converted to an NSObject

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
objectName

- A C string containing the name of this object

objectFunctions

- A static array of mappings between Lua object method names and C function pointers. This provides the public API of the objects. Note that this array is also used as the metatable, so special functions (e.g. "__gc") should be included here

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:

Every C function pointer must point to a function of the form: static int someFunction(lua_State *L);


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

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

a function of the type pushNSHelperFunction

className

a C string containing the class name of the NSObject type this function can convert

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:

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

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

the name of the module to load

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:

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

+ (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
delegate

An object that responds to -(void)logForLuaSkinAtLevel:(int)level withMessage:(NSString *)theMessage

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:

Calling this method leaves the lua thread pointer in the same state that invoking [LuaSkin sharedWithState:NULL] will.


sharedWithState:


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

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

the lua state representing the lua thread to assign to the LuaSkin internal lua thread pointer. If NULL, the lua state that was created by +(id)sharedWithDelegate:(id)delegate will be used.

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:

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

- (NSPoint)tableToPointAtIndex:(int)idx; 
Parameters
idx

the index on lua stack which contains the table to convert

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:

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

- (NSRect)tableToRectAtIndex:(int)idx; 
Parameters
idx

the index on lua stack which contains the table to convert

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:

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

- (NSSize)tableToSizeAtIndex:(int)idx; 
Parameters
idx

the index on lua stack which contains the table to convert

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
idx

the index on lua stack which contains the data to convert

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:

This method is equivalent to invoking [LuaSkin toNSObjectAtIndex:idx withOptions:LS_NSNone]. See toNSObjectAtIndex:withOptions:.


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
idx

the index on lua stack which contains the data to convert

options

options for the conversion made by using the bitwise OR operator with members of LS_NSConversionOptions.

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:

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

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

a message to attach to the top of the stack trace

level

- the level at which to start the traceback

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
firstArg

- An integer that defines the first acceptable Lua argument type. Possible values are defined here . Followed by zero or more integers of the same possible values. The final value MUST be LS_TBREAK

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:

The final argument MUST be LS_TBREAK, to signal the end of the list