Last week, Mac OS X 10.6 Snow Leopard was released!
Snow Leopard represents a lot of hard work by a lot of folks at Apple and at seeded third-party developers, and it really shows.
Now that it’s shipped, I can actually talk about some of the especially cool things this release has for developers.
Various pieces of Mac OS X and iPhone documentation have said for quite a while that the “preferred” method is now to use ISO-639-1 (two-letter) or ISO-639-2 (three-letter) language codes codes for localization purposes. Out of the box, Xcode’s project templates still use “English” rather than “en” as their default localization.
How can you use the ISO-639 language codes everywhere in your project, rather than in just your non-English localizations?
It’s pretty straightforward, but it does require hand-editing of your Xcode project file. This means that before doing anything else, you **must quit Xcode and Interface Builder**.
The first step is to rename your existing localizable resource directories *on disk* from `English.lproj` to `en.lproj`. You can do it at the Terminal or in the Finder. If you’re using an SCM system such as Subversion, use it to do the renaming so it preserves your file history and such as well.
The next step is to adjust how your existing localizable resources are referenced in your Xcode project file. Open the `project.pbxproj` file inside your Xcode project in a plain text editor such as TextEdit (rather than Xcode) and replace **all but one** occurrences of the string `English` with the string `en`. The one you don’t want to replace is in a property under the PBXProject section named `knownRegions`: This is an array of localizations Xcode knows about. Just make sure `en` is at the end of the array:
knownRegions = (
English,
Japanese,
French,
German,
en,
);
At this point, this should be the only place `English` appears in your `project.pbxproj` file.
Finally — and this is the important step, and non-discoverable step — you need to **add a property** to the `project.pbxproj` file to tell Xcode what the Development Region for your project is. Again, this gets put into the PBXProject section before the `knownRegions` key from above (Xcode will alphabetize the keys when saving your project for you); it should look like this:
developmentRegion = en;
The default value of this key within Xcode is `English` and Xcode won’t write the key into the project if the default isn’t changed. However, there’s no user interface within Xcode for actually changing this property, making it non-discoverable. Furthermore, if you are changing your project to use `en` as its default localization, and you *don’t* change this property, you won’t be able to add new localizations by inspecting your resources. (This is a known issue.)
At this point, you can save your modified `project.pbxproj` file and open your project again in Xcode. There’s one more thing you’ll have to change, this time in your product’s Info.plist file (or your products’ Info.plist files), before you can get back to work: You need to change the `CFBundleDevelopmentRegion` property to `en` rather than `English`.
Once you’ve made that change, you should safely be able to use your Xcode project normally, adding localized variants of your resources, building and running, and so on, and everything should Just Work — now using modern ISO language codes instead of the English language names!
In the past, I’ve talked about ways to easily write unit tests for Cocoa applications, including [tests for user interfaces using target-action][1] and [tests for interfaces using Cocoa bindings][2]. There are some strategies you can apply to make writing tests for Cocoa code even easier, though. They’re just straightforward object-oriented programming, but sometimes we can forget that all the techniques you might use in your main code base can also be applied to our test code.
So here’s one trick that you can use in writing tests for Cocoa user interfaces, especially in ways that will make test-driven development easier.
### Use a Common Base Class with Check Methods
The first, probably most important thing to do is *use your own common base class* for your tests. Don’t derive your tests directly from `SenTestCase`; instead, derive them from your own `MyTestCase` class that in turn derives from `SenTestCase`. This gives you a place to put all of the customization that’s appropriate for your project.
Sometimes you might need a series of assertions to verify some particular state. However, that series of assertions will be the same every time you need to verify that state. Or the assertions themselves aren’t very *intention revealing* so you always wind up putting a comment above them describing what they’re really doing.
### Checking Target-Action
A simple example of this is checking a target-action connection in a user interface. Say you have a view controller that presents a collection of objects managed by an array controller. Its view has an Add button that should send `-addObject:` to the array controller. You might write a test for it like this:
– (void)testAddButtonSendsAddObjectToArrayController {
STAssertEquals([viewController.addButton target], viewController.arrayController,
@”The Add button should target the array controller.”);
STAssertEquals([viewController.addButton action], @selector(addObject:),
@”The Add button should send the -addObject: action.”);
}
That’s not too difficult to understand, but it could be made simpler — it could be done in a single assertion. You’d just write a method to check both the target and action at once and then use that method from your test, like this:
// in your test base class…
/*! Tells whether the control sends the action to the target. */
– (BOOL)checkControl:(NSControl *)control
sendsAction:(SEL)action
toTarget:(id)target
{
return ([control action] == action)
&& ([control target] == target);
}
// in the tests specifying the view controller’s behavior…
– (void)testAddButtonSendsAddObjectToArrayController {
STAssertTrue([self checkControl:viewController.addButton
sendsAction:@selector(addObject:)
toTarget:viewController.arrayController],
@”The Add button’s action should send -addObject: to the array controller.”);
}
That makes the intention behind the entire test a lot clearer, and it makes writing the test easier & safer since you can’t (say) forget to check either the target or the action.
It *does* lose a tiny bit of information: If the test fails, you’ll have to look at your xib file instead of the failure message to determine whether it’s because the target or the action isn’t set as you’ve specified. However, the trade-off in making the test easier to read and write is worth it here.
### Checking Outlets
This is even worthwhile for single assertions, such as those you’d use to test that your outlets are connected in the first place. For example, you might initially write a test that your view controller is your table view’s delegate like this:
– (void)testViewControllerIsTableViewDelegate {
STAssertEquals([viewController.tableView delegate], viewController,
@”The table view’s delegate should be the view controller.”);
}
Rewriting it to be more intention-revealing with a simple check method would make it look like this:
// in your test base class…
/*! Tells whether the outlet is connected to the given destination. */
– (BOOL)checkOutlet:(id)outlet connectsTo:(id)destination {
return outlet == destination;
}
// in the tests specifying the view controller’s behavior…
– (void)testViewControllerIsTableViewDelegate {
STAssertTrue([self checkOutlet:[viewController.tableView delegate]
connectsTo:viewController],
@”The table view’s delegate should be the view controller.”);
}
You’re not saving any code by writing your test this way — you’re actually writing more — but its *complexity* has gone down because it requires less effort to see what it’s actually trying to do.
### Checking Bindings
This is even worthwhile in situations where you may still need a few extra assertions. For example, Cocoa bindings are specified using a lot more information than just outlets and target-acton connections; you won’t always want to check (and specify the value of) all of it, but you can easily make the common parts clearer.
Going back to our Add button example, as is typical its enabled state should be bound to the array controller’s `canAdd` property. Writing a test to specify this involves using `-infoForBinding:` and interpreting the results, which takes a couple lines of code and a couple of assertions:
– (void)testAddButtonEnabledStateIsBoundToArrayControllerCanAdd {
NSDictionary *bindingInfo = [viewController.addButton infoForBinding:NSEnabledBinding];
STAssertNotNil(bindingInfo,
@”The Add button’s enabled state should be bound.”);
id observedObject = [bindingInfo objectForKey:NSObservedObjectKey];
STAssertEquals(observedObject, viewController.arrayController,
@”The Add button’s enabled state should be bound to the array controller.”);
NSString *observedKeyPath = [bindingInfo objectForKey:NSObservedKeyPathKey];
STAssertEqualObjects(observedKeyPath, @”canAdd”,
@”The Add button’s enabled state should be bound through the ‘canAdd’ key path.”);
}
This isn’t too complicated, but it does start to get tedious, especially given that you have to remember to distinguish between `STAssertEquals` (pointer equality) and `STAssertEqualObjects` (object equivalence). Let’s put the tedium in one place:
/*! Tells whether the object’s binding is connected through the given key path. */
– (BOOL)checkObject:(id)source
hasBinding:(NSString *)binding
toObject:(id)destination
through:(NSString *)keyPath
{
NSDictionary *bindingInfo = ;
id observedObject = [bindingInfo objectForKey:NSObservedObjectKey];
NSString *observedKeyPath = [bindingInfo objectForKey:NSObservedKeyPathKey];
return (bindingInfo != nil)
&& (observedObject == destination)
&& [keyPath isEqualToString:observedKeyPath];
}
// in the tests specifying the view controller’s behavior…
– (void)testAddButtonEnabledStateIsBoundToArrayControllerCanAdd {
STAssertTrue([self checkObject:viewController.addButton
hasBinding:NSEnabledBinding
toObject:viewController.arrayController
through:@”canAdd”],
@”The Add button’s enabled state should be bound to the array controller’s ‘canAdd’ property.”);
}
Much clearer!
[1]: https://eschatologist.net/blog/?p=10 “Unit testing Cocoa user interfaces: Target-Action”
[2]: https://eschatologist.net/blog/?p=12 “Unit testing Cocoa user interfaces: Cocoa Bindings”
I listened to a recent episode of the [cocoaFusion:][1] podcast about properties and dot notation today. There were a few interesting points brought up, but I felt a couple of the most important reasons to use `@property` declarations and dot notation weren’t addressed.
The biggest reason I see to use a different notation for both property declaration and property access than for method declaration and sending messages — even if property access ultimately results in a message send, as it does in Objective-C 2.0 — is **separation of state and behavior**.
In the ur-OOP days of Smalltalk, state was supposed to be *encapsulated* within objects *entirely*. This has become Smalltalk dogma and some developers have tried to propagate it to Objective-C: The idea that objects should *never* expose their state to each other, but instead only vend *behaviors*. It makes a certain amount of sense if you see objects purely as actors.
However, in today’s modern world we understand that objects aren’t *just* actors. Objects both “do things” *and* “represent things;” they’re nouns. And they have both *internal* state that they use in managing their behavior and *external* state they expose to the world.
You can use the same mechanism to do both, as Smalltalk does and as Objective-C did before 2007. However, it turns out that it can make a lot more sense to use different syntax to represent the distinct concepts, even if they’re handled by the same underlying mechanism.
For example, I might have a Person class and an NSViewController subclass that presents a Person instance in a view. The API to my Person class might look like this:
@interface Person : NSObject
@property (copy) NSString *name;
@property (copy) NSImage *picture;
@end
This sends a strong signal to the users of the class that `name` and `picture` are *external* state for a Person instance, leading me to write code like this:
Person *person = [[Person alloc] init];
person.name = @”Chris”;
person.picture = pictureOfChris;
The intent of this code is clear: I’m not asking `person` to do anything, I’m just manipulating its external state. That may cause it to do things as a side-effect, but at least in the code snippet I’m looking at, I’m just interested in changing some state.
Now let’s see what the NSViewController might look like:
@interface PersonViewController : NSViewController
@property (retain) Person *person;
– (BOOL)updatePicture;
@end
And let’s see how I’d use one, assuming it’s been instantiated and wired up in my view hierarchy already:
selectedPersonViewController.person = person;
if ([selectedPersonViewController updatePicture]) {
// note elsewhere that the person’s picture is updated
}
Even though the `-updatePicture` method has no arguments and returns a `BOOL` I (1) don’t make it a property and (2) don’t use dot notation to invoke it. Why not, since it fits the *form* of a property? Because it doesn’t fit the *intent* of a property. I’m actually telling the view controller to perform some action, not just changing some state, and I want the intent of that to be clear to a reader of the above code.
That brings me to the other major reason to both declare properties using `@property` and use dot notation to access them: Xcode. The code completion technology in Xcode tries hard to provide you with a good default completion and good choices in the completion list. But this can be very difficult, especially with the combination of Objective-C’s dynamic dispatch and the sheer size of the frameworks: There are hundreds (!) of methods declared in categories on NSObject as a result of categories describing informal protocols, and any of those methods could be valid on an arbitrary instance.
Dot notation, on the other hand, is **not** valid on arbitrary objects. Even though it compiles to exactly the same sort of `objc_msgSend` dynamic dispatch that bracket notation does, from a type system perspective it actually **requires** a declaration of the property being accessed to work correctly. The reason for this is that the name of a property is not necessarily the name of the message selector to use in dispatch; think of a property `hidden` whose underlying getter method is named `-isHidden`.
This means that tools like Xcode can provide a much more streamlined experience for properties using dot notation. If I write the above code in Xcode, rather than MarsEdit, Xcode will not offer completions like `-autorelease` and `-retainCount` when I type `person.` — it will only offer me the properties it knows are on Person.
Now, you *can* invoke arbitrary getters or setters (so long as they have a corresponding getter) using dot notation. The compiler doesn’t require an `@property` declaration for the use of dot notation, just a declaration. I could have declared the `Person.name` property like this:
@interface Person : NSObject
– (NSString *)name;
– (void)setName:(NSString *)value;
@end
The compiler will compile `person.name = @”Chris”;` just fine with this declaration, to an invocation of `-[Person setName:]` — but Xcode won’t offer you code completion for it if you don’t use `@property` to declare it. By not offering to complete non-`@property` properties for dot notation, Xcode avoids offering you *bad* completions like `autorelease` and `retain` that are technically allowed but are abominable style.
Of course, one complication is that many frameworks on Mac OS X predate `@property` declarations and thus don’t expose their state this way. That means Xcode won’t offer you completions for their state with dot notation until those frameworks do. Fortunately for iPhone developers, UIKit uses `@property` declarations pervasively. You should too.
To sum up:
* Use `@property` to declare the state exposed by your objects.
* Use dot notation to get and set objects’ state.
* Use method declarations to declare the behavior exposed by your objects.
* Use bracket notation to invoke objects’ behavior.
This results in intention-revealing code that clearly separates state and behavior both in declaration and use.
[1]: http://www.cocoafusion.net/ “cocoaFusion: podcast”
As of today, I’ve been with Apple for five years, working on developer tools.
It’s been great and I look forward to many more years of improving the experience for people creating great Mac and iPhone software!
In a few weeks, it will be **four years** since Mac OS X 10.4 Tiger was first released. That was the first release to include Core Data. It will also be about **one and a half years** since Mac OS X 10.5 Leopard was released, with significant enhancements to the Core Data API.
It’s pretty safe to start using Core Data in your applications now. You certainly don’t need to wrote directly to the low-level SQLite API any more.
There was a question recently on Stack Overflow asking how to handle cross-model relationships in managed object models. Now, the poster wasn’t asking about how to handle relationships across persistent stores — he was asking how to handle splitting a model up into pieces such that the pieces could be recombined.
It turns out that this is somewhat straightforward to do using Core Data. Let’s say you have a simple model with Song and Artist entities. I’ll write it out here in a pseudo-modeling language for ease of reading:
MusicModel = {
Song = {
attribute title : string;
attribute duration : float;
to-one-relationship artist : Artist,
inverse : songs,
delete-rule : nullify;
userInfo = { };
};
Artist = {
attribute name : string;
to-many-relationship songs : Song,
inverse : artist,
delete-rule : cascade;
userInfo = { };
};
};
Now let’s say you want to split this up into two models, where Song is in one and Artist is in the other. You could just try and create two xcdatamodel files in Xcode, one with each entity, and wire the relationships together after loading them and merging them with +[NSManagedObjectModel modelByMergingModels:]. Except that won’t work: Relationships with no destination entity won’t be compiled by the model compiler.
What else might you try? You could try just putting dummy entities in for relationships to point to. However, merging models will fail then, because NSManagedObjetModel won’t merge models that have entity name collisions.
It turns out, though, that you can merge models very easily by hand, by taking advantage of the way Core Data’s model-description objects handle the NSCopying protocol. All you have to do is create your destination model, loop through every entity in each of your source models, and copy every entity that you haven’t tagged as a stand-in using a special key in their userInfo dictionary.
Why does this work? The trick is that before you tell a persistent store coordinator to use a model, that model is mutable and references relationship destination entities and inverse relationships by name. So you can have only a minimal representation of Artist in one model, and a minimal representation of Song in another model:
SongModel = {
Song = {
attribute title : string;
attribute duration : float;
to-one-relationship artist : Artist,
inverse : songs,
delete-rule : nullify;
userInfo = { };
};
Artist = {
/* Note no attributes. */
to-many-relationship songs : Song,
inverse : artist,
delete-rule : cascade;
userInfo = { IsPlaceholder = YES; };
};
};
ArtistModel = {
Song = {
/* Note no attributes. */
to-one-relationship artist : Artist,
inverse : songs,
delete-rule : nullify;
userInfo = { IsPlaceholder = YES; };
};
Artist = {
attribute name : string;
to-many-relationship songs : Song,
inverse : artist,
delete-rule : cascade;
userInfo = { };
};
};
Then, when you write some code to combine them, the merged model will wind up with the full definition of Song and the full definition of Artist. Here’s an example of the code you might write to do this:
- (NSManagedObjectModel *)mergeModelsReplacingDuplicates:(NSArray *)models {
NSManagedObjectModel *mergedModel = [[[NSManagedObjectModel alloc] init] autorelease];
// General strategy: For each model, copy its non-placeholder entities
// and add them to the merged model. Placeholder entities are identified
// by a MyRealEntity key in their userInfo (which names their real entity,
// though their mere existence is sufficient for the merging).
NSMutableArray *mergedModelEntities = [NSMutableArray arrayWithCapacity:0];
for (NSManagedObjectModel *model in models) {
for (NSEntityDescription *entity in [model entities]) {
if ([[[entity userInfo] objectForKey:@"IsPlaceholder"] boolValue]) {
// Ignore placeholder.
} else {
NSEntityDescription *newEntity = [entity copy];
[mergedModelEntities addObject:newEntity];
[newEntity release];
}
}
}
[mergedModel setEntities:mergedModelEntities];
return mergedModel;
}
This may seem like a bit of overhead for this simple example. The critical thing to see above is that only that which is necessary for model consistency is in the placeholder entities. Thus you only need the inverse relationship from Song to Artist in ArtistModel. Say you wanted to add a Picture entity related to the Artist entity — you don’t have to add that to both models, only to ArtistModel. The benefit of this method for merging models should then be pretty apparent: It gives you the ability to make your model separable, just like your code.
I thought the proper terminology was worth pointing out, since I’ve seen — and heard — some misuses lately.
* **[LLVM][1]** is the Low-Level Virtual Machine and the project surrounding it.
* **[LLVM-GCC][2]** is a compiler that uses GCC for its front-end and LLVM for its back-end.
* **[Clang][3]** is the C language family front-end that is part of the LLVM project. It’s a parser, semantic analyzer, and code generator — in other words, a compiler front-end that uses LLVM for its back-end.
* **[The Clang Static Analyzer][4]** is what people have been trying out lately, to find subtle bugs in their and other projects. It’s a great tool.
I just thought this was important to mention, because people have been referring to “LLVM” instead of “LLVM-GCC” in reference to the compiler included in Xcode 3.1, and people have been referring to “Clang” instead of “the Clang Static Analyzer” in reference to what they’ve been using to find bugs in their projects.
[1]: http://llvm.org/
[2]: http://llvm.org/docs/CommandGuide/html/llvmgcc.html
[3]: http://clang.llvm.org/
[4]: http://clang.llvm.org/StaticAnalysis.html
What’s wrong with this code?
– (void)registerForNotificationsFromTask:(NSTask *)task ( {
[[NSNotificationCenter defaultCenter]
addObserver:self
selector:@selector(taskDidTerminateNotification:)
name:@”NSTaskDidTerminateNotification”
object:task];
}
If you didn’t notice anything wrong, look again.
What’s bad about this is that it’s passing a **string literal** instead of a **global variable** for the notification name. The code should really look like this:
– (void)registerForNotificationsFromTask:(NSTask *)task ( {
[[NSNotificationCenter defaultCenter]
addObserver:self
selector:@selector(taskDidTerminateNotification:)
name:NSTaskDidTerminateNotification
object:task];
}
Isn’t that better? (Among other things, Xcode will offer to complete the `NSTaskDidTerminateNotification` global variable for you — unlike the contents of a string literal.)
This is a bug that often results from copying & pasting from documentation into code. “I need this notification, it needs to be a string, so I’ll just put `@””` around it.” The *type* of a notification name is, in fact, `NSString` but you don’t have to pass a *string literal* for that. Instead, pass the global variable that exists for each notification name and you’re guaranteed that the right thing will happen.
If you’re creating and using your own notifications, be sure to follow the Cocoa pattern and create your own global variables containing the notification name. Otherwise you’re at the mercy of typos within string literals.
**Update:** Sanjay Samani helpfully pointed out that by *constant string* I meant *string literal*. Thanks, Sanjay! I’ve updated my post with this correction. (Not sure where my memory was…)
The time is upon us once again — WWDC time!
As I have the past few years, I’ll be in San Francisco all week, staying at the Hotel Kabuki in Japantown.
And of course, I’ll be around the conference all week — especially in the labs. Come by and say hi, and I’ll be happy to help with any questions you have!