objc

local objc = require'objc'

Jump To: Features | Quick Tutorial | Memory Management | Main API | Reflection API | Debug API

Features

• 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

Limitations

• 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
  • UPDATE: you can use cbframe as a workaround. Enable it with objc.debug.cbframe = true; now all the 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 set return value into (note: self isn't passed, 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.
objc.load'Foundation'

--you can also load sub-frameworks like this:
objc.load'Carbon.HIToolbox'

--which is the same as using relative paths:
objc.load'Carbon.framework/Versions/Current/Frameworks/HIToolbox'

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)

Subclassing

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

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

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

--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)
   print(line:UTF8String())
end)
str:enumerateLinesUsingBlock(block)

--create a block with its method type encoding given manaully.
--for type encodings see:
--   https://code.google.com/p/jscocoa/wiki/MethodEncoding
--   https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Articles/ocrtTypeEncodings.html
local block = objc.block(function(line, stop)
   print(line:UTF8String())
end, 'v@^B'}) --retval is 'v' (void), line is '@' (object), stop is '^B' (pointer to BOOL)
str:enumerateLinesUsingBlock(block)

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

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

Reflection API

Debug API

Credits

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

Bridging

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

Inspection

• 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