lights FAQ Forum

Native OS APIs


Obj-C & Cocoa bridge

local objc = require'objc'


  • Coverage
    • full access to Cocoa classes, protocols, C functions, structs, enums, constants
    • access to methods, properties and ivars
    • creating classes and overriding methods
    • exploring and searching the Objective-C runtime
  • Platforms
    • tested with OSX 10.9 (32bit and 64bit)
  • Dependencies
    • none for Cocoa (XML parser included), expat for non-standard bridgesupport files
  • Type Bridging
    • methods and functions return Lua booleans
    • Lua numbers, strings and tables can be passed for NSNumber, NSStrings, NSArray and NSDictionary args
    • string names can be passed for class and selector args
    • Lua functions can be passed for block and function-pointer args without specifying a type signature
    • overriding methods does not require specifying the method type signature
      • method signatures are inferred from existing supermethods and conforming protocols
        • formal and informal protocols supported
    • function-pointer args on overriden methods and blocks can be called without specifying a type signature
  • GC Bridging
    • attaching Lua variables to classes and objects
      • Lua variables follow the lifetime of Obj-C objects
      • Lua variables attached to classes are inherited
    • automatic memory management of objects and blocks
      • blocks are refcounted and freed when their last owner releases them
  • Speed
    • aggressive caching all-around
    • no gc pressure in calling methods after the first invocation
    • fast, small embedded XML parser


Blocks, function callbacks and overriden methods are based on ffi callbacks which come with some limitations:

  • can't access the vararg part of the function, for variadic functions/methods
  • can't access the pass-by-value struct args or any arg after the first pass-by-value struct arg
  • can't return structs by value

To counter this, you can use cbframe as a workaround. Enable it with objc.debug.cbframe = true and now all problem methods and blocks will receive a single arg: a pointer to a D_CPUSTATE struct that you have to pick up args from and write the return value into. Note that self isn't passed in this case, the cpu state is the only arg.

Quick Tutorial

Loading frameworks

--load a framework by name; `objc.searchpaths` says where the frameworks are. you can also use full paths.
--classes and protocols are loaded, but also C constants, enums, functions, structs and even macros.

--you can also load sub-frameworks like this:

--which is the same as using relative paths:

Creating and using objects

--instantiate a class. the resulting object is retained and released on gc.
--you can call `release()` on it too, for a more speedy destruction.
local str = objc.NSString:alloc():initWithUTF8String'wazza'

--call methods with multiple arguments using underscores for ':'. last underscore is optional.
--C constants, enums and functions are in the objc namespace too.
local result = str:compare_options(otherStr, objc.NSLiteralSearch)


--create a derived class. when creating a class, say which protocols you wish it conforms to,
--so that you don't have to deal with type encodings when implementing its methods.
objc.class('NSMainWindow', 'NSWindw <NSWindowDelegate>')

--add methods to your class. the selector `windowWillClose` is from the `NSWindowDelegate` protocol
--so its type encoding is inferred from the protocol definition.
function objc.NSMainWindow:windowWillClose(notification)

--override existing methods. use `objc.callsuper` to call the supermethod.
function objc.NSMainWindow:update()
   return objc.callsuper(self, 'update')

Converting between Lua and Obj-C types

local str = objc.toobj'hello'             --create a NSString from a Lua string
local num = objc.toobj(3.14)              --create a NSNumber from a Lua number
local dic = objc.toobj{a = 1, b = 'hi'}   --create a NSDictionary from a Lua table
local arr = objc.toobj{1, 2, 3}           --create a NSArray from a Lua table

local s = objc.tolua(str)
local n = objc.tolua(num)
local t1 = objc.tolua(dic)
local t2 = objc.tolua(arr)

Adding Lua variables (luavars)

--add Lua variables to your objects - their lifetime is tied to the lifetime of the object.
--you can also add class variables - they will be accessible through the objects too.
objc.NSObject.myClassVar = 'I can live forever'
local obj = objc.NSObject:new()
obj.myInstanceVar = 'I live while obj lives'
obj.myClassVar = 5 --change the class var (same value for all objects)

Adding Lua methods

Lua methods are just Lua variables which happen to have a function-type value. You can add them to a class or to an instance, but that doesn't make them "class methods" or "instance methods" in OOP sense. Instead, this distinction comes about when you call them:

function objc.NSObject:myMethod() end
local str = objc.toobj'hello'   --create a NSString instance, which is a NSObject
str:myMethod()                  --instance method (str passed as self)
objc.NSString:myMethod()        --class method (NSString passed as self)

As you can see, luavars attached to a class are also inherited.

If this looks like a lot of magic, it is. The indexing rules for class and instance objects (i.e. getting and setting object and class fields) are pretty complex. Have a look at the API sections "object fields" and "class fields" to learn more.

Accessing properties & ivars

--get and set class and instance properties using the dot notation.
local pr = objc.NSProgress:progressWithTotalUnitCount(123)
print(pr.totalUnitCount) --prints 123
pr.totalUnitCount = 321  --sets it

--get and set ivars using the dot notation.
local obj = objc.NSDocInfo:new()
obj.time = 123
print(obj.time) --prints 123

Creating and using blocks

--blocks are created automatically when passing a Lua function where a block is expected.
--their lifetime is auto-managed, for both synchronous and asynchronous methods.
local str = objc.NSString:alloc():initWithUTF8String'line1\nline2\nline3'
str:enumerateLinesUsingBlock(function(line, stop)
   print(line:UTF8String()) --'char *' return values are also converted to Lua strings automatically

--however, blocks are slow to create and use ffi callbacks which are very limited in number.
--create your blocks outside loops if possible, or call `collectgarbage()` every few hundred iterations.

--create a block with its type signature inferred from usage.
--in this case, its type is that of arg#1 to NSString's `enumerateLinesUsingBlock` method.
local block = objc.toarg(objc.NSString, 'enumerateLinesUsingBlock', 1, function(line, stop)

--create a block with its method type encoding given manaully.
--for type encodings see:
local block = objc.block(function(line, stop)
end, 'v@^B'}) --retval is 'v' (void), line is '@' (object), stop is '^B' (pointer to BOOL)

More goodies

Look up anything in Cocoa by a Lua pattern:

   ./luajit objc_test.lua inspect_find foo

Then inspect it:

   ./luajit objc_test.lua inspect_class PAFootprint

Even more goodies

Check out the unit test script, it also contains a few demos, not just tests.
Check out the undocumented objc_inspect module, it has a simple cmdline inspection API.

Memory management

Memory management in objc is automatic. Cocoa's reference counting system is tied to the Lua's garbage collector so that you don't have to worry about retain/release. The integration is not air-tight though, so you need to know how it's put together to avoid some tricky situations.

Strong and weak references

Ref. counting systems are fragile: they require that retain() and release() calls on an object be perfectly balanced. If they're not, you're toast. Thinking of object relationships in in terms of weak and strong references can help a lot with that.

A strong reference is a retained reference, guaranteed to be available until released. A weak reference is not retained and its availability depends on context.

A strong reference has a finalizer that calls release() when collected. A weak reference doesn't have a finalizer.

Calling release() on a strong reference releases the reference, and removes the finalizer, turning it into a weak reference. You should not call release() on a weak reference.

Return values are strong

Cocoa's rules say that if you alloc an object, you get a strong (retained) reference on that object. Other method calls that return an object return a weak (non-retained) reference to that object. Lua retains all object return values so you always get a strong reference. This is required for the alloc():init() sequence to work, and it's generally convenient.

Callback arguments are weak

Object arguments passed to overriden methods (including the self argument), blocks and function pointers, are weak references, not tied to Lua's garbage collector. If you want to keep them around outside the scope of the callback, you need to retain them:

local strong_ref
function MySubClass:overridenMethod()
   strong_ref = self:retain() --self is a weak ref. it needs to be retained.

Luavars and object ownership

You should only use luavars on objects that you own. Luavars go away when the last strong reference to an object goes away. Setting Lua vars on an object with only weak references will leak those vars! Even worse, those vars might show up as vars of other objects!

Strong/weak ambiguities

If you create a NSWindow, you don't get an unconditionally retained reference to that window, contrary to Cocoa's rules, because if the user closes the window, it is your reference that gets released. The binding doesn't know about that and on gc it calls release again, giving you a crash at an unpredictable time (export NSZombieEnabled=YES can help here). To fix that you can either tell Cocoa that your ref is strong by calling win:setReleasedWhenClosed(false), or tell the gc that your ref is weak by calling ffi.gc(win, nil). If you chose the latter, remember that you can't use luavars on that window!

Main API

global objects
objc namespace for loaded classes, C functions, function aliases, enums, constants, and this API
objc.load(name|path[, option]) load a framework given its name or its full path
option 'notypes': don't load bridgesupport file
objc.searchpaths = {path1, ...} search paths for frameworks
objc.findframework(name|path) -> path, name find a framework in searchpaths
objc.class'name' -> cls class by name (objc.class'Foo' == objc.Foo)
objc.class(obj) -> cls class of instance
objc.class('Foo', 'SuperFoo <Protocol1, ...>') -> cls create a class which conforms to protocols
objc.class('Foo', 'SuperFoo', 'Protocol1', ...) -> cls create a class (alternative way)
objc.classname(cls) -> s class name
objc.isclass(x) -> true|false check for Class type
objc.isobj(x) -> true|false check for id type
objc.ismetaclass(cls) -> true|false check if the class is a metaclass
objc.superclass(cls|obj) -> cls|nil superclass
objc.metaclass(cls|obj) -> cls metaclass
objc.isa(cls|obj, supercls) -> true|false check the inheritance chain
objc.conforms(cls|obj, protocol) -> true|false check if a class conforms to a protocol
objc.responds(cls, sel) -> true|false check if instances of cls responds to a selector
objc.conform(cls, protocol) -> true|false declare that a class conforms to a protocol
object fields
access an instance field, i.e. try to get, in order:
- an instance luavar
- a readable instance property
- an ivar
- an instance method
- a class field (see below)
obj.field = val
set an instance field, i.e. try to set, in order:
- an existing instance luavar
- a writable instance property
- an ivar
- an existing class field (see below)
- a new instance luavar
class fields
access a class field, i.e. try to get, in order:
- a class luavar
- a readable class property
- a class method
- a class luavar from a superclass
cls.field = val
function cls:method(args...) end
set a class field, i.e. try to set, in order:
- an existing class luavar
- a writable class property
- an instance method
- a conforming instance method
- a class method
- a conforming class method
- an existing class luavar in a superclass
- a new class luavar
type conversions
objc.tolua(x) -> luatype convert a NSNumber, NSString, NSDictionary, NSArray to a Lua number, string, table respectively. anything else passes through.
objc.toobj(x) -> objtype convert a Lua number, string, or table to a NSNumber, NSString, NSDictionary, NSArray respectively. anything else passes through.
objc.ipairs(arr) -> next, arr, 0 ipairs for NSarray.
objc.override(cls, sel, func[,mtype|ftype]) -> true|false override an existing method, or add a method which conforms to one of the conforming protocols. returns true if the method was found and overriden.
objc.callsuper(obj, sel, args...) -> retval call the method implementation of the superclass of an object.
objc.swizle(cls, sel1, sel2[, func]) swap implementations between sel1 and sel2. if sel2 is not an existing selector, func is required.
objc.SEL(name|sel) -> sel create/find a selector by name
sel:name() -> s selector name (same as tostring(sel))
blocks and callbacks
objc.toarg(cls, sel, argindex, x) -> objtype convert a Lua value to an objc value - used specifically to create blocks and function callbacks with an appropriate type signature for a specific method argument.
objc.block(func, mtype|ftype) -> block create a block with a specific type encoding.

Reflection API

objc.protocols() -> iter() -> proto loaded protocols (formal or informal)
objc.protocol(name|proto) -> proto get a protocol by name (formal or informal)
proto:name() -> s protocol name (same as tostring(proto))
proto:protocols() -> iter() -> proto inherited protocols
proto:properties() -> iter() -> prop get properties (inherited ones not included)
proto:property(proto, name, required, readonly) -> prop find a property
proto:methods(proto, inst, req) -> iter() -> sel, mtype get method names and raw, non-annotated type encodings
proto:mtype(proto, sel, inst, req) -> mtype find a method and return its raw type encoding
proto:ctype(proto, sel, inst, req[, for_cb]) -> ctype find a method and return its C type encoding
objc.classes() -> iter() -> cls loaded classes
objc.protocols(cls) -> iter() -> proto protocols which a class conforms to (formal or informal) -> iter() -> prop` instance properties
use metaclass(cls) to get class properties, name) -> prop instance property by name (looks in superclasses too)
objc.methods(cls) -> iter() -> meth instance methods
use metaclass(cls) to get class methods
objc.method(cls, name) -> meth instance method by name (looks in superclasses too)
objc.ivars(cls) -> iter() -> ivar ivars
objc.ivar(cls) -> ivar ivar by name (looks in superclasses too)
prop:name() -> s property name (same as tostring(prop))
prop:getter() -> s getter name
prop:setter() -> s setter name (if not readonly)
prop:stype() -> s type encoding
prop:ctype() -> s C type encoding
prop:readonly() -> true|false readonly check
prop:ivar() -> s ivar name
meth:selector() -> sel selector
meth:name() -> s selector name (same as tostring(meth))
meth:mtype() -> s type encoding
meth:implementation() -> IMP implementation (untyped)
ivar:name() -> s name (same as tostring(ivar))
ivar:stype() -> s type encoding
ivar:ctype() -> s C type encoding
ivar:offset() -> n offset

Debug API

objc.debug.errors (true) log errors to stderr
objc.debug.printcdecl (false) print C declarations on stdout
objc.debug.logtopics= {topic = true} (empty) enable logging on some topic (see source code)
objc.debug.errcount = {topic = count} error counts
solving C name clashes = bar load a string constant under a different name = bar load an enum under a different name = bar load a type under a different name = bar load a const under a different name = bar load a global function under a different name
loading frameworks
objc.debug.loadtypes (true) load bridgesupport files
objc.debug.loaddeps (false) load dependencies per bridgesupport file (too many to be useful)
objc.debug.lazyfuncs (true) cdef functions on the first call instead of on load
objc.debug.checkredef (false) check incompatible redefinition attempts (makes parsing slower)
objc.debug.usexpat (false) use expat to parse bridgesupport files
gc bridging = true declare that method foo already retains the object it returns


  • Cosmin Apreutesei, May 2014, public domain.
  • Ideas and code from TLC by Fjölnir Ásgeirsson (c) 2012, MIT license.

Future developments

NOTE: I don't plan to work on these, except on requests with a use case. Patches/pull requests welcome.


  • function-pointer args on function-pointer args (recorded but not used - need use cases)
  • test for overriding a method that takes a function-pointer (not a block) arg and invoking that arg from the callback
  • auto-coercion of types for functions/methods with format strings, eg. NSLog
    • format string parser - apply to variadic functions and methods that have the printf_format attribute
  • return pass-by-reference out parameters as multiple Lua return values
    • record type modifiers O=out, N=inout
  • auto-allocation of out arrays using array type annotations
    • c_array_length_in_result - array length is the return value
    • c_array_length_in_arg - array length is an arg
    • c_array_delimited_by_null - vararg ends in null - doesn't luajit do that already?
    • c_array_of_variable_length - ???
    • c_array_of_fixed_length - specifies array size? doesn't seem so
  • sel_of_type, sel_of_type64 - use cases?
  • core foundation stuff
    • cftypes xml node - use cases?
    • already_retained flag
  • operator overloading (need good use cases)


  • list all frameworks in searchpaths
  • find framework in searchpaths
  • report conforming methods, where they come from and mark the required ones, especially required but not implemented
  • inspection of instances
    • print class, superclasses and protocols in one line
    • print values of luavars, ivars, properties
    • listing sections: ivars, properties, methods, with origin class/protocol for each

Type Cache

The idea is to cache bridgesupport data into Lua files for faster loading of frameworks.

  • one Lua cache file for each framework to be loaded with standard 'require'
    • dependencies also loaded using standard 'require'
  • save dependency loading
  • save cdecls - there's already a pretty printer and infrastructure for recording those
  • save constants and enums
  • save function wrappers
  • save mtas (find a more compact format for annotations containing only {retval='B'} ?)
  • save informal protocols

Last updated: 23 months ago | Edit on GitHub

Pkg type:Lua+ffi
Version: r7-9-g0923229
Last commit:
License: PD
Requires: luajit 
Required by: cairo  nw  videoinput