How Cappuccino handles pass-by-reference APIs in Cocoa.

I’ve been using Cappuccino at work recently and I came across a corner of Objective-J that I previously didn’t know about: how to use enumerateObjectsUsingBlock.

One of the nice things about Objective-C is that it has blocks.  Blocks allow you to make functions that take other functions as arguments, all while preserving scope. One of the most popular block-using APIs is the NSArray method enumerateObjectsUsingBlock. It takes a block that has three arguments: the current value of the iteration, the current index and a reference to a Boolean stop variable. If you set the variable to YES the loop will stop (much like the break keyword, which only works to break out of while and for loops.)

This is a problem for JavaScript because it always passes by value. Since it’s very cheap to create objects in JavaScript you could just pass an object with a property you can set, but that means that you have to remember the property name to set and the caller has to remember to copy that value back out. The Cappuccino developers thought of using a function that closes over an object in the parent scope via a macro called AT_REF.

To use a cappuccino AT_REF you simply call it and pass in the new value you want to set. Like so:

[array enumerateObjectsUsingBlock:function (item, i, stop) { 
    stop(YES);
}];

In the implementation of enumerateObjectsUsingBlock you’ll see something like the following:

var stop = NO; 
for (var i = 0; i < length; i++) { 
    block(arr[i], i, BY_REF(stop)); 
    if (stop) 
        break; 
}

The AT_REF macro expands to something like:

(function(val) { 
    if (arguments.length) 
        return (stop = val); 
    return val; 
}) 

That way you can both set the value by calling it with an argument and get the value by calling it with no arguments.

It’s brilliant if you ask me. But then again, pretty obvious when you think about it.

In the future the devs would like to integrate this into the language by using @ref() and @deref(), (hence the name of the macro).

To define methods that use AT_REF in your own code you can simply @import <Foundation/Ref.h>.  Clients of your API just need to know to call the argument to set and get it’s value.