Fun with Objective-C

Getting the IMP of the current method

Sat, 03 Dec 2011 17:16:32 -0800

Once in a very great while, you come across a weird situation where you want to know the IMP of the current method. I’ll just say right now that if you think you need this, you probably don’t. That’s how rare this situation is.

Regardless, it’s an interesting question. How do you get the function pointer for the currently-executing method?

A few years ago, Matt Gallagher came up with a clever solution to this using a compiler function called __builtin_return_address(). His code still works great with the LLVM 3.0 compiler. My only beef with it is that there’s a lot of looping going on. He’s looping over the entire superchain, over every single method, looking at the IMP’s address and comparing them to another pointer.

Pretty Pretty

This morning I was thinking about a question on Stack Overflow and thought of another way to get the current IMP:

static inline IMP __CurrentIMP(const char *info, SEL _cmd) {
  IMP imp = NULL;
  if (info[0] == '-' || info[0] == '+') {
    NSString *tmp = [NSString stringWithCString:info+2 encoding:NSUTF8StringEncoding];
    NSRange r = [tmp rangeOfString:@" "];
    NSString *className = [tmp substringToIndex:r.location];
    Class thisClass = NSClassFromString(className);
    if (thisClass != nil) {
      Method m = NULL;
      if (info[0] == '+') {
        m = class_getClassMethod(thisClass, _cmd);
      } else {
        m = class_getInstanceMethod(thisClass, _cmd);
      }
      if (m != NULL) {
        imp = method_getImplementation(m);
      }
    }
  }
  return imp;
}

#define CurrentIMP __CurrentIMP(__PRETTY_FUNCTION__, _cmd)

So, what’s going on? Basically, we’re parsing a special string that’s generated by the compiler and then doing a single lookup. The important bit is the __PRETTY_FUNCTION__. This is a built-in “magic” value that, when compiled, becomes a very nice-looking description of the current function (it’s “pretty”).

For a regular C function, __PRETTY_FUNCTION__ becomes a const char* that includes the name of the function and some type information. The main() function has a __PRETTY_FUNCTION__ of this: "int main(int, const char **)". Ooooo, pretty! :)

An Objective-C method’s pretty description doesn’t include type information, but it does include some very important information. Let’s say we have a class Bar that has this method:

- (id)doAwesomeThingWithFoo:(Foo *)foo {
    ...
}

The pretty description for this is "-[Bar doAwesomeThingWithFoo:]". Here, we see two very important pieces of information:

The first character is a -, indicating that the method is an instance method
The name of the implementing class is clearly visible.

The selector is also in there, but we would have that anyway through _cmd, so that’s not very interesting. (We could forego passing in _cmd to the __CurrentIMP function and parse it out of the description, but since _cmd is there already, let’s use that.)

The really important thing to realize here is that the name of the class in the description is the class on which the method is implemented, and not the class of any instance. This makes sense, because this is all happening at compile time, not runtime.

Armed with these two pieces of information, we can quickly get the appropriate IMP. First, we do some really simple string parsing to extract the name of the class from the description, and turn it in to a Class object with the NSClassFromString function.

Now that we have the Class and the selector (we’re just using _cmd), we can get the IMP. However, we need to know which runtime function we should be using. For this, we can simply look at the first character in the description string. If it’s a +, then we use the class-specific function, otherwise we’ll use the instance-specific function.

These functions (class_getClassMethod and class_getInstanceMethod) both return Method references. From this Method, we can simply use method_getImplemention to get the method’s IMP. Simple!

Some may ask: why are we getting the Method reference instead of using the class_getMethodImplementation function, which returns an IMP directly? The answer for that is that while that would usually work, it would fail for methods that have large return values (i.e. where the size of the return value is larger than sizeof(id)). In that case, we’d have to use the class_getMethodImplementation_stret function, which means we’d have to get an NSMethodSignature object and check the methodReturnLength to decide which function to use. I figure that getting the Method and asking it for its IMP is probably simpler.

Now, there is a downside to this approach (that are not present in Matt’s implementation). Since this is relying on a compile time detail (the pretty description), this totally and utterly breaks when you start add methods, swizzling implementations, make IMPs from blocks, etc.

But for those times where you, for whatever reason, need to know what your IMP is, this works pretty well.

Steve Weller pointed on on Twitter that if you combine this code with Matt’s version, you can reasonably determine when a method has been swizzled. Cool!

Dumbfounded

Tue, 05 Jul 2011 20:39:03 -0700

I was just shown an NSPredicate that dumbfounded me for several reasons:

It’s using five nested SUBQUERY expressions. In other words, a SUBQUERY within a SUBQUERY within a SUBQUERY within a SUBQUERY within a SUBQUERY.
It works
It’s reasonably fast
Core Data correctly handles it on a SQLite store
It’s the only way the author could accomplish what he needed in a “reasonable” way.

What sort of NSPredicate is this? Here you go:

static NSString *kCommonRequestFragment = @"SUBQUERY(things, $thing, SUBQUERY($thing.thingType.spams, $spam, SUBQUERY($spam.ham.eggs, $egg, SUBQUERY($egg.foo.bars, $bar, SUBQUERY($bars.baz.blips, $blip, $blip.bing.id == %@).@count > 0).@count > 0).@count > 0).@count > 0).@count > 0";

- (NSFetchRequest *)fetchRequestForSomeObjects {
    NSFetchRequest *theRequest = [self templateFetchRequest];
    NSString * thePredicateFormatString = [NSString stringWithFormat:@"(%@) AND (%@)", @"SUBQUERY(participatingObjects, $object, $object.property.id == %@).@count > 0", kCommonRequestFragment];
    [theRequest setPredicate:[NSPredicate predicateWithFormat:thePredicateFormatString, self.aThing.anID, self.aThing.anotherID]];

    return theRequest;
}

- (NSFetchRequest *)fetchRequestForOtherObjects {
    NSFetchRequest *theRequest = [self templateFetchRequest];
    NSString * thePredicateFormatString = [NSString stringWithFormat:@"(%@) AND (%@)", @"SUBQUERY(participatingObjects, $object, $object.property.id == %@).@count == 0", kCommonRequestFragment];
    [theRequest setPredicate:[NSPredicate predicateWithFormat:thePredicateFormatString, self.aThing.anID, self.aThing.anotherID]];

    return theRequest;
}

Insane.

Parsing Mathematical Expressions

Sun, 05 Jun 2011 10:10:43 -0700

A while ago, I was looking for a library to parse NSString objects as mathematical expressions. I wanted to be able to take a string like @"2+3*4" and get back 14. I found two easy ways to do this: GCMathParser and NSPredicate (of course!).

GCMathParser is a library by Graham Cox for parsing strings as equations. It uses a parser generated by BISON as the primary engine, with a straight-forward Objective-C wrapper for easy interaction. In terms of raw speed, it’s blazingly fast. However, I found one major flaw with it: it is impossible to extend. It has support for a bunch of built-in functions (all your basic trigonometric functions, rounding, etc), but if you wanted to add support for bitwise operators (bitwise AND, OR, NOT, XOR, etc), you’re totally out of luck. There’s no way to do it without regenerating an entirely new parser.

NSPredicate, as I’ve mentioned before, can also parse numerical expressions. Like GCMathParser, it has a couple of flaws:

The associativity of the power operator is wrong. The string @"2 ** 3 ** 2" is parsed as (2 ** 3) ** 2, or 64. This is “left associativity”. In practical terms, it means that when you have a bunch of the same operator in a row like that, the left-most one is evaluated first. However, exponentiation is supposed to be right associative. In other words, that expression should’ve been parsed as 2 ** (3 ** 2), or 512. This is a major flaw, and it’s been reported: rdar://8692313.
The syntax for custom functions is absurdly bizarre. NSExpression, the class that makes up the basic components of a predicate, does not have any trigonometric functions built-in. However, NSExpression does support defining your own functions, but with a ridiculously complex syntax. For my purposes, I wanted to take a regular user-entered string and parse it, without requiring the user to know about FUNCTION() syntax. I could’ve tried manipulating the user’s string to transform sin(<#expression#>) into FUNCTION(<#expression#>, 'sinValue') and then written a sinValue category method on NSNumber, but if I was going to write a transformer to manipulate the string, I might as well write a full-fledged parser.

So, I wrote DDMathParser to be extensible, correct, and easy to understand.

The Guts

I tried writing a formal grammar for parsing a mathematical expression, and actually got pretty far. However, when writing the recursive descent parser to match strings against this grammar, I came up against some conceptual hurdles that I couldn’t work around. I also didn’t like that modifying the grammar, even slightly, usually meant making extremely large changes to the parser. Eventually I gave up with that sort of parser and came up with something else.

There are several phases to parsing a string using this parser:

Tokenization
Grouping
Resolving

Tokenization

Tokenization is simply the process of breaking up the string into chunks. If I have the string @"1 + 2 - 3 * 4 / 5", then after tokenization I’m going to end up with 9 tokens: 1, +, 2, -, 3, *, 4, /, and 5. No attempt is made to try to resolve anything. I will note, however, that this is the point at which implicit multiplication is made explicit. More on that later.

The tokenization process simply reads through the string character-by-character, and decides what to do with the characters it finds. The general rules it follows are:

If it reads a digit or a decimal point, attempt to parse a number (a number is defined as anything recognizable by NSNumberFormatter).
If parsing a number failed and the character is matched by [a-zA-Z0-9] (any alphanumeric character), then attempt to parse the name of a function.
If parsing a function name failed and the character is the $ character, then attempt to parse a variable name.
If parsing a variable name failed, then attempt to parse an operator.
If parsing an operator failed, then abort with an error.

It’s also at this point that we figure out if - and + are acting, for example, as negation or subtraction. The basic rule is: if a - or + is preceded by another operator that’s not a closing parenthesis (or it’s the first token in the steam), then it’s the unary operator (negation, etc). Otherwise it’s the binary operator.

Grouping

If tokenization succeeds, the tokens are grouped into “terms”. To explain what goes on, we’ll look at an example. Let’s say we’re parsing the string @"2 * (pi()sin(dtor(45)) + max($a, 42)/54)". The token stream will have generated these tokens:

2 * ( pi ( ) * sin ( dtor ( 45 ) ) + max ( $a , 42 ) / 54 )

Grouping organizes the terms hierarchically. This is done recursively, and is also where parentheses are checked to make sure they’re balanced. Visually, we’ll end up with something like this:

As you can see, no attempt has been made to define precedence. The step is only to break up the tokens into parenthetical “levels”.

Resolving

After the terms have been grouped, we can break things up further. We take the root group and iterate over the terms in its “subterms” array to find the indices of the operators with the highest precedence. Precedence is defined via an enum:

enum {
    DDPrecedenceBitwiseOr = 0,
    DDPrecedenceBitwiseXor,
    DDPrecedenceBitwiseAnd,
    DDPrecedenceLeftShift,
    DDPrecedenceRightShift,
    DDPrecedenceSubtraction,
    DDPrecedenceAddition = DDPrecedenceSubtraction,
    DDPrecedenceDivision,
    DDPrecedenceMultiplication = DDPrecedenceDivision,
    DDPrecedenceModulo,
    DDPrecedenceUnary,
    DDPrecedenceFactorial,
    DDPrecedencePower,
    DDPrecedenceParentheses,

    DDPrecedenceUnknown = -1,
    DDPrecedenceNone = -2
};

Parentheses produce the highest precedence, followed by the power operator, then the factorial operator, then any generic unary operator (negation, bitwise NOR, etc), and then down on through the standard mathematical operators, with bitwise OR having the lowest precedence. Subtraction has the same precedence as addition, since subtraction is really just the addition of a negative number. Likewise, division is the same as multiplication by the number’s multiplicative inverse.

Once we have the indices of the operators with the highest precedence, we’ll need to look and see if we have more than one. If we do, then we look at the associativity of the operator to see if we should choose the first (ie, left associative) or last (ie, right associative) operator. After picking an operator, we can look at the terms around the operator, recursively resolve those terms (if necessary), and then combine those resolved terms and the operator into a new group term. This is when we check to make sure that operators have all the necessary terms. It’s at this point, for example, that @"2+" would fail to parse, because + is a binary operator, but the string only has a single term. @"+2", however, would parse, because + would already have been recognized as a unary operator.

After resolution has finished, our object hierarchy now looks like this:

At this point, the term hierarchy is fully organized, and it’s a simple matter to convert it into expression objects for storage and/or evaluation.

Implicit Multiplication

When writing mathematical expressions, we understand that we can express the multiplication of two terms without actually writing a multiplication operator. For example, 5x is 5 * x, and 6(9) is the same thing as 6 * 9. I really wanted the parser to handle implicit multiplication, and it turns out it was very simple to implement. When tokenizing a string, a * token is inserted between two tokens if a Number, Variable, or Close Parenthesis token is followed by anything except an operator token (unless it’s an Open Parenthesis token). With this setup:

5$x becomes 5 * $x
6(9) becomes 6 * (9)
2sin($x) becomes 2 * sin($x)

Analysis

As I see it, there are several major advantages to this parser:

The only limit on valid numbers is that they be recognizable by NSNumberFormatter. This means that we can use numerical types with far more precision than a double, and much larger than a long long. For all but the trigonometric functions, calculations are done with NSDecimal structs boxed in NSDecimalNumber objects.
Function resolution doesn’t happen until evaluation time. This allows us to parse strings like bogus(42), but not care that the bogus function doesn’t exist. With the ability to delay function recognition, we’re free to define any extra functions that we want.
Parsing is not defined by a grammar. If we need to add a new operator, it’s very feasible, and won’t require generating a whole new parser.
Operator associativity can be changed on-the-fly. If, for some reason, you need exponentiation to be left associative rather than right associative, it’s extremely easy to change that with a simple property change.

The primary downside of this parser, however, is speed. Since we’re operating with several different layers of Objective-C objects, rather than on a C string, there’s going to be an enormous^* speed discrepancy between GCMathParser and DDMathParser. However, what we lose in speed is more than made up for in extensibility and accuracy.

The code is available for your perusal at GitHub: https://github.com/davedelong/DDMathParser

^{* by “enormous”, I mean “about 2 orders of magnitude, but still able to parse and evaluate a complex string in a fraction of a second”}

Updates

4 Jun 2011: original posting
5 Jun 2011: added description of recognizing unary operators

Subclassing NSInputStream

Thu, 14 Apr 2011 21:57:22 -0700

Subclassing NSInputStream is a problem that has been plaguing Cocoa developers for a long time. Googling “subclass nsinputstream” reveals that people have been having issues with this for six or seven years. While the documentation seems to indicate that it should be fairly straightforward, actually trying to do so reveals several hairy spots.

For example, if you try to use a custom NSInputStream as the body of an NSURLRequest, you’ll get an exception that your input stream doesn’t respond to _scheduleInCFRunLoop:forMode:. So then you create an empty stub for that method. You’re good, right? Nope! Now you fail with an unimplemented _setCFClientFlags:callback:context:. So you implement that, and you’re good, right? Nope! You fail now with an unimplemented _unscheduleFromCFRunLoop:forMode:. So you put that in as a stub, and you’re good? Well, you don’t get any more exceptions… but nothing ever gets read from your stream. Minor details…

Well, the dark night of ignorance and inability is over!

BJ Homer has just posted an article on how he got his NSInputStream subclass to work. He’s even posted a demo on his GitHub account. I won’t spoil any of the details here; go read it for yourself! His solution is really quite clever.

(And as a side note, at the time of this writing, there are 2,272 occurrences of the letter ‘n’ on his blog’s home page.)

How to learn Cocoa

Sat, 19 Mar 2011 01:38:15 -0700

This is something any experienced Cocoa developer has been asked at least half a dozen times:

“What’s the best way to learn Objective-C/Cocoa?”

I have two answers to this question:

Be curious
Don’t be satisfied

Be Curious

Curiosity is the heart of learning anything. If you can cultivate a deep curiosity about the Objective-C language and the Cocoa frameworks, then I guarantee that you will have absolutely no problem learning them. I’m not talking about the “oh, wouldn’t it be nice to know how to write iOS apps” kind of curiosity. I’m talking about the “why does the @ sign go there? What’s up with these asterisks all over the place? Why are things done in this order instead of that order” kind of curiosity. Gaining this level of curiosity can be very difficult, especially at first. But without it, you’ll never really understand how everything is working together.

If you’re familiar with an sort of object-oriented programming language, then Objective-C, as a language, shouldn’t be that hard to pick up. Just use get used to the square brackets, and things will look pretty familiar. Learning the frameworks, on the other hand, will take a lifetime. The Cocoa Frameworks (Foundation, AppKit/UIKit, CoreData, CoreFoundation, MapKit, QuickLook, MediaAccess, CoreLocation, etc) are enormously broad. The Foundation framework itself is composed of 173 public classes and 31 protocols. That’s a lot of pre-built code, and that’s just one framework out of a couple dozen! There are some classes you will come to know very intimately (NSString, NSArray, NSDictionary), but even they will surprise you every now and then. Plus, Apple actively develops these frameworks; they’re being improved and optimized and expanded all the time. There will always be more to learn.

Along with the capabilities of the classes, there are patterns to learn. Design patterns describe how classes interact with each other. Some of the first ones you’ll encounter are Model View Controller, Delegation, and Class Clusters. There are many others, and they’re in there for a very good reason. As you come across them, take the time to understand why they’re there.

Do the same with the classes in the frameworks. Explore them. Play with them. Abuse them. Ask yourself:

What problem does this solve?
How does it solve the problem?
Can you use these abilities for anything else?
How would you implement this class if you had to? (And then go do it!)

Be curious.

Don’t Be Satisfied

As you learn Cocoa, the code you write will be terrible. Understand that. But don’t accept it. There is always a different way you could do something, and quite often one of those different ways is a better way. Always seek out opportunities to improve your code and to find different and better ways to organize it. Sometimes this will mean rewriting things half a dozen times. But you know what? That’s OK! All developers experience this. If you can learn to not be satisfied with your code, you’ll quickly learn how to iterate over it and make improvements here, tweak some stuff there, maybe rip out some layer of control and totally reorganize it… This is what programming is all about. Don’t be satisfied with how your code looks. Strive to make it a work of art and a thing of beauty.

Final Thoughts

So there you have it! These are my recommendations for how to learn Cocoa. They have served me well, and I think they pretty much summarize what I’ve observed about experienced developers.

Oh, and by the way…

Know what a pointer is.
Memorize the memory management rules.
Never invoke -retainCount.

Welcome to Cocoa.

How I do my singletons

Thu, 24 Feb 2011 02:14:54 -0800

This is something that comes up again and again. How do you make a true singleton in Objective-C? I was just asked this the other night, so I decided to write up my version of an Objective-C singleton.

For starters, there’s an example in the documentation on how you could make a singleton. It’s a pretty bizarre implementation. StackOverflow.com has a nice long discussion on what people consider acceptable singletons. Peter Hosey wrote an in-depth post about it a while back as well, with a different example of what he considers a good singleton.

Go read those articles, then come back.

Have you read them yet? Good.

I think Peter’s overview of what makes a singleton is very good. In particular, he has several criteria that, if met, help define a singleton. They are:

+sharedFramistan always returns the same object.
+alloc/-init always produce the same object (which, itself, is the same object as +sharedFramistan).
+alloc/-init will not return an object confused by multiple init messages.
Over-releasing causes a crash.
Keeping +alloc/+allocWithZone:/-retain balanced with release never causes a crash.
If [super init] returns a different object, +alloc/-init won’t break.

Over the couple years, I’ve developed my own singleton pattern. I think it’s pretty simple, it gets the job done, and it’s fairly idiot-proof. It does have a drawback, which is that the singleton exists for the lifetime of the process; it is not lazily created. If that’s a problem for you, well then this singleton probably isn’t for you. Other than that, it has served me very well.

So, without further ado, here it is:

// DDFramistan.h
@interface DDFramistan : NSObject

+ (id) sharedFramistan;

@end

// DDFramistan.m

static DDFramistan *_sharedFramistan = nil;

__attribute__((constructor)) static void construct_singleton() {
  NSAutoreleasePool * p = [[NSAutoreleasePool alloc] init];
  _sharedFramistan = NSAllocateObject([DDFramistan class], 0, nil);
  [p drain];
}

__attribute__((destructor)) static void destroy_singleton() {
  NSAutoreleasePool * p = [[NSAutoreleasePool alloc] init];
  NSDeallocateObject(_sharedFramistan), _sharedFramistan = nil;
  [p drain];
}

@implementation DDFramistan

+ (id)sharedFramistan {
  return _sharedFramistan;
}

+ (id) allocWithZone:(NSZone *)zone {
  return [[DDFramistan sharedFramistan] retain];
}

@end

The only really weird things going on here are those two functions, construct_singleton() and destroy_singleton(). What’s up with those? Basically, by tacking that __attribute__((constructor)) onto the function declaration, this function will get invoked before execution enters main(). As such, we have to set up an NSAutoreleasePool for the off-chance that we happen to create any autoreleased objects during singleton creation. Also, I’m using the NSAllocateObject() function, which is pretty much the same thing as class_createInstance(). That’s going to allocate a new object for me on the heap, with all of the members of that object set to 0 (ie, it’s essentially using calloc()).

Similarly, the __attribute__((destructor)) function is one that will get executed after returning from main() (or exit()). This one isn’t quite as necessary, since if the program is exiting, all the memory is going to get cleaned up anyway. However, if you’ve got shared resources (file descriptors, etc), this would be the place to clean them up. Again, we wrap the deallocation in an NSAutoreleasePool to catch any autoreleased objects that may get created in the process (which would be weird, but not impossible).

As for the methods on the singleton itself, they’re really straight forward:

+sharedFramistan returns our singleton
+allocWithZone: returns the static singleton, retained (just like it’s supposed to)
Since we have no -init method, we’ll simply inherit the one belonging to NSObject. -[NSObject init] is documented to simply return self, so we’re safe to invoke it as many times as we want.

Other than that, it’s a perfectly normal Objective-C object. Let’s go over Peter’s list and see how we did:

+sharedFramistan always returns the same object.
Yep, we got that.
+alloc/-init always produce the same object (which, itself, is the same object as +sharedFramistan).
Yep, we got that too.
+alloc/-init will not return an object confused by multiple init messages.
Since the init method does do anything, this is easily accomplished.
Over-releasing causes a crash.
We’re not doing anything bizarre with memory management, so if you over-release the singleton, it will get deallocated prematurely, and accessing it after that will cause your program to crash. So… check.
Keeping +alloc/+allocWithZone:/-retain balanced with release never causes a crash.
Again, we’re good here. As long as you don’t over-release, this object will never go away.
If [super init] returns a different object, +alloc/-init won’t break.
Since we don’t implement -init, we don’t have to worry about this.

Looks pretty good!

Now, the moment we’ve all been waiting for…

Is DDFramistan a true singleton?

NO.

DDFramistan is not a true singleton. A true singleton would never allow another instance of the object to be created under any circumstances. Unfortunately, Objective-C has fun things like NSAllocateObject() and class_createInstance() that allow us to easily bypass all of the normal object creation business, and there’s nothing we can do about that (that I can think of). So while it’s unlikely that you would ever create another instance of DDFramistan, it’s not impossible. And therefore, this is not a true singleton.

But it’s probably good enough (and it’s about as close as you can get).

History

24 Feb 2011 - Original post
24 Feb 2011 - removed unnecessary init method, as suggested in the comments

Why do Strings in Objective-C have to be preceded with an @?

Thu, 24 Feb 2011 00:55:00 -0800

Simple: because if you left it off, it wouldn’t be an NSString*. It’d be a char *. Any time you see the @ symbol in Objective-C code, you can know that it’s so that the compiler can do something special there that C doesn’t natively support.

So with that in mind, we have:

@catch: declare a scope for catching a thrown execution
@class: forward declare a class
@compatibility_alias: specify an alias for a class name
@dynamic: specify that property accessors will by dynamically implemented at runtime
@encode: ask for a character array representing the type of a variable
@end: close an interface declaration or an implementation block
@finally: declare code that will be executed after an @try and/or @catch block execute
@implementation: implement a class definition
@interface: define a class API (also used for categories and class extensions)
@optional: declare the optional nature of protocol methods
@package: declare the scope of ivars
@private: declare the scope of ivars
@property: declare a class property
@protected: declare the scope of ivars
@protocol: declare a list of methods that conforming objects might implement
@public: declare the scope of ivars
@required: declare the required nature of protocol methods
@selector: declare the the stuff that immediately follows in the parentheses is a method name
@synchronized: declare a section of code that is atomic
@synthesize: direct the compiler to generate accessor methods for properties (that you haven’t implemented yourself)
@throw: throw an NSException
@try: begin a block in which an exception might be thrown
@"": declare a constant string

That’s all I can remember off the top of my head. I’m sure I’ve forgotten one or two. A more complete list (with better explanations) can be found in the documentation.

Since this is an Obj-c blog,I have a question for you

why would they make another C with OOP,what's wrong with C++?

Sun, 30 Jan 2011 17:08:00 -0800

It sounds from your question like Objective-C has only been around for a couple years. Believe it or not, Objective-C is an old language! It was invented in 1986 by Tom Love and Brad Cox (only 3 years after C++). It was adopted by NeXT as the lingua franca of the NeXT OS, and was the language that Sir Tim Berners-Lee used to write the world’s first web browser.

Objective-C and C++ were created with very different purposes. The former was an experiment in combining the dynamism of Smalltalk on top of the C language. C++, on the other hand, was built to add the object oriented features of Simula to C, but without suffering from Simula’s performance problems.

PC Week summed up this difference nicely in their 3 Nov 1997 edition:

Objective-C is the result of adding object facilities to C with the goal of making programmers more productive. The result differs greatly from C++, which adds objects to C without making computers less efficient: quite a different goal.

I’ve found this to be the case in my own use of the language. I’ve learned several languages over the past decade, and Objective-C is the only language I’ve actually enjoyed using. Of course, each language has its flaws (including Objective-C), but Objective-C gives me the organization of an object-oriented language like C++ or Java, the power of a dynamic and flexible runtime like a scripting language, all built on top of the power of C. There are tradeoffs to this (Objective-C tends to be slightly slower than C++), but for me, the benefits far outweigh the costs.

I've really been enjoying your posts, but you don't have any personal information on your site, as far as I could find. Who are you?

Tue, 25 Jan 2011 00:39:14 -0800

No one of consequence…

My name is Dave DeLong. I’m a frameworks engineer at Apple, where I work on the UIKit framework. I spend my spare time with my family and playing with the Objective-C runtime. I also believe that the existence of chocolate and peanut butter are proof that there is a God, and that He loves us.

Using custom functions with NSExpression

Tue, 25 Jan 2011 00:28:00 -0800

There are a bunch of built-in functions in the NSExpression class that allow you to do some pretty neat stuff. They are: average:, sum:, count:, min:, max:, median:, mode:, stddev:, add:to:, from:subtract:, multiply:by:, divide:by:, modulus:by:, sqrt:, log:, ln:, raise:toPower:, exp:, ceiling:, abs:, trunc:, random, random:, now, floor:, uppercase:, lowercase:, bitwiseAnd:with:, bitwiseOr:with:, bitwiseXor:with:, leftshift:by:, rightshift:by:, onesComplement:, and noindex:. That’s a lot of functions! You have your arithmetic functions, some multi-parameter functions, some bitwise functions, and a few miscellaneous ones thrown in for good measure.

But… what if you want to find the factorial of a number? Or use any sort of trigonometric function? Or say you wanted to do something much more complex? Are you out of luck?

Fortunately, no. There is a way to do custom functions in NSExpression, with the downside that the syntax is a little bit more complex than your standard functions.

The built-in functions can be written as if they were actual functions: now(), sqrt(42), 6 * 9, etc. Unfortunately, we cannot do that with our custom functions. Oh well. Let’s get over that and move on.

The Syntax

The syntax for all functions is:

FUNCTION(operand, 'function', arguments, ...)

In a nutshell, the result of the function is the result of invoking the function method on operand, while passing in the arguments as parameters to the method.

If we dive into one of the NSExpressions produced by a standard function, we learn some interesting things. Let’s example the function “6*9”.

NSExpression * e = [(NSComparisonPredicate *)[NSPredicate predicateWithFormat:@"6*9 = 1"] leftExpression];

The -operand of this expression is another NSExpression. In the case of these built-in functions, it turns out that it’s a constant value expression encapsulating a Class object of type _NSPredicateUtilities. Some runtime introspection on this object shows that it has a whole bunch of class methods that correspond to all of the built-in functions, along with one that’s not listed in the documentation: castObject:toType:. We previously discussed using this function with advanced date predicates.

The operand is an NSExpression (as opposed to an id), because the object receiving the method could be the result of another expression.

The function in our multiplication expression is “multiply:by:”, as we would expect.

The arguments to our multiplication is an NSArray of NSExpression objects. They are expressions for the same reason that the operand is an NSExpression. In our example, we have two expressions, both representing NSNumbers as constant values.

Custom Functions

Now that we understand the syntax behind FUNCTION(), it should be fairly obvious how to go about making our own functions. Here’s what we need:

An object on which to operate.
A method to invoke
Parameters to pass in (optional)

So let’s say we want to add a factorial function. We have two options on how to approach this:

Make our factorial method receive the number as a parameter
Make our factorial method operate on a number directly

I personally prefer the latter approach, since the syntax is slightly less complicated. Here’s what we would do:

@interface NSNumber (FactorialExpression)

- (NSNumber *) factorial;

@end

@implementation NSNumber (FactorialExpression)

- (NSNumber *) factorial {
  double baseValue = [self doubleValue];
  double result = tgamma(baseValue+1);
  return [NSNumber numberWithDouble:result];
}

@end

(This method uses the Gamma Function, which allows for computing the factorial of non-integral numbers)

Then in our format string, we would express it like this:

FUNCTION(4.2, 'factorial')

If we evaluate that expression, we get 32.57809605033135, as we were hoping! The key thing here is realizing that 4.2 will be boxed in an NSNumber, which means that the factorial method will be invoked on NSNumber.

Venturing Toward the Absurd

OK, we’ve got basic functions down. What about functions that take arguments? For this next example, we’ll take a look at a custom function being used in StackKit, a framework for accessing the Stack Overflow API.

At the heart of StackKit is a URL generation system that will turn a combination of an NSPredicate, an NSSortDescriptor, and a Class into an HTTP GET request that can be used to retrieve data from one of the Stack Exchange sites (like http://stackoverflow.com). Due to the limited nature of the API, only certain predicates and sort descriptors are allowed, and only in very specific combinations.

One of the parts of “validating” an NSPredicate is to verify that it is only using allowed keyPaths, and that these keyPaths are being compared with specific operators. Each of the “RequestBuilder” classes vends an NSDictionary called the recognizedPredicateKeyPaths. This dictionary is a map of keyPaths (as the key) to an NSArray of NSNumber objects. The NSNumbers box an NSPredicateOperatorType.

Since each builder recognizes different keyPaths and different operators, I had to get a little creative. Here’s what the code looks like:

p = [NSPredicate predicateWithFormat:@"FUNCTION(%@, 'sk_matchesRecognizedKeyPathsAndOperators:', SELF.recognizedPredicateKeyPaths) == YES", predicateToValidate];
[builders filterUsingPredicate:p];

In this case, predicateToValidate is the user-supplied NSPredicate. I’m going to be passing this predicate in as the operand to my FUNCTION. The method that will be invoked on it is @selector(sk_matchesRecognizedKeyPathsAndOperators:), which is conveniently provided via an NSPredicate category. Finally, the argument to this function is the dictionary of the current request builder. If the sk_matchesRecognizedKeyPathsAndOperators: method returns YES, then we’ve passed this particular step of the validation.

The code for the NSPredicate method is fairly simple; it simply iterates through all of the keys in the NSDictionary, then extracts the subpredicates of the “predicateToValidate” for each key. Of these subpredicates, if there’s one that’s using an operator that’s not recognized, then we abort and return NO. Otherwise we’ll get to the end, find that all of our subpredicates are using allowed operators, and return YES.

The result of those two lines of code is that the builders array will be filtered to only contain the builders that allow the left keyPaths and operators that are specified in the user-provided predicate.

(For more fun, exciting, and absurd uses of NSPredicate, check out SKRequestBuilder.m.)

A Caution

One of the things to be wary of when using custom functions is that all of the parameters to the method must be objects, and the return value of the method must also be an object! This means that you cannot do:

[NSPredicate predicateWithFormat:@"FUNCTION('a', 'isEqual:', 'a') == YES"];

If you try to evaluate that predicate, it will crash. NSExpression is attempting to cast the result of the isEqual: method as an object. However, (id)1 is not an object recognizable by Objective-C, no matter how you cast it.

Instead, if you needed to do this, you’d add a method that simply boxed the result in the appropriate NSValue object and use that method:

@implementation NSString (CustomFunction)

- (NSNumber *) dd_isEqual:(id)other {
  return [NSNumber numberWithBool:[self isEqual:other]];
}

@end

...

FUNCTION('a', 'dd_isEqual:', 'a')

This will work just fine.

Wrap Up

Custom functions in NSExpression are pretty neat. You don’t find yourself using them very often, but when you need them, they can be extremely handy!

What the heck is SUBQUERY?

Wed, 12 Jan 2011 22:38:00 -0800

One of the lesser known bits of NSPredicate is the SUBQUERY() function. The documentation for a subquery expression explains a little bit about what’s going on, but it takes a while to understand when it’s really useful.

Let’s break it down.

The Syntax

A subquery expression takes 3 arguments:

A collection
A variable name
A predicate

The Collection

The collection can be one of the two standard Cocoa collection: NSArray and NSSet (or some subclass of them). This collection can be hard-coded in, or it can be the result of another expression (like a keyPath expression or the like). A hard-coded collection would look like:

SUBQUERY(%@, ...

A keyPath expression would look like:

SUBQUERY(contents, ...

With the stipulation that [self contents] (or self.contents if you prefer) must return an NSArray or NSSet.

The Variable

The SUBQUERY is going to iterate over the collection, gathering certain objects. We need a way to represent what each item in the collection is, and for that we use the variable.

Variables in an NSExpression (or NSPredicate format string) take the form $identifier, where identifier is a valid C-style identifier. Most examples of SUBQUERY generally use $x as the variable. It’s short and to-the-point.

It’s the second argument in the expression:

SUBQUERY(contents, $x, ...

The Predicate

A predicate, as we know, is a statement that evaluates to true or false. In the case of the subquery, the predicate will be evaluated for each object (represented by the variable) in the collection. If the predicate returns true, then that object will be included as part of the resulting collection.

SUBQUERY(contents, $x, $x.property = 'foo' and $x.number = 42)

TL;DR

A SUBQUERY() expression is the functional equivalent of doing this:

NSPredicate * p = [NSPredicate predicateWithFormat:@"property = 'foo' and number = 4"];
NSArray * results = [[self contents] filteredArrayUsingPredicate:p];

If this were expressed as a subquery in a predicate, it would be:

NSPredicate * p = [NSPredicate predicateWithFormat:@"SUBQUERY(contents, $x, $x.property = 'foo' and $x.number = 42) ..."];  
//with some operation to use the resulting collection in a comparison or something

So what?

Now that we get what the various bits of a subquery expression are, let’s ask the real question: when is this ever useful?

To be honest, the answer to this is “not often”. However, when you need it, it’s incredibly useful.

Rule of thumb

The general rule of thumb on when you should consider using SUBQUERY is this:

If you have a collection (A) of objects, and each object has a collection (B) of other objects, and you’re trying to filter A based on some varying attributes (at least 2) of the objects in B, then you should probably be using SUBQUERY.

Example

Let’s say you have a bunch of Project objects, and each Project has a bunch of ToDo items. A ToDo item has a completionDate (an NSDate) and a user (a name). You want to find all projects that have a todo item that was completed by Joey (so completionDate is not nil and user is “Joey”). We’re going to display these in a “Joey’s Recent Projects” group (or something).

Our first reaction might be a predicate that uses ANY in there, like:

ANY todos.completionDate != nil AND ANY todos.user == joey

Unfortunately, that would give us projects that have at least one completed ToDo and that has a ToDo whose user is Joey. However, they don’t have to be the same ToDo.

The proper predicate is:

SUBQUERY(todos, $todo, $todo.completionDate != nil AND $todo.user = 'Joey').@count > 0

This predicate will be evaluated against each Project. First, we’ll get the collection of ToDo objects by evaluating the todo keyPath on the Project. Then for each item ($todo) in the array of ToDo objects, we’re going to check and see if that object’s completionDate is non-nil and if that object’s user is "Joey". If that’s true, then it’ll be added to the resulting collection.

When the SUBQUERY completes, we’ll have an array of ToDo items that were completed by Joey. At this point, we retrieve the number of items in that collection (via the @count keyPath) and see if it’s greater than 0. If it is, then the corresponding Project will be added to the final array. In this manner, we can retrieve all Projects that have ToDos completed by Joey.

Creating an advanced NSPredicateEditorRowTemplate

Wed, 24 Nov 2010 21:01:56 -0800

In a recent post I covered how to make a simple NSPredicateEditorRowTemplate. In this post we’re going to go a bit deeper.

The Setup

In our last example, we did some simple date comparisons, where we were comparing an NSTimeInterval against a property that represented a duration. For example, if we had an array of Song objects, then we could use that row template to construct a predicate to find all songs that were longer than 5 minutes (duration > 300). But what if our objects don’t have a duration property? What if they have a date property, such as the date this song was added? Well, we can use the built-in initializers of NSPredicateEditorRowTemplate to create a template where the right expression type is NSDateAttributeType. This is all well and good, but it has a fundamental flaw: It can only compare against static dates.

In other words, I can easily create a row template for predicates of the form <a date> <is, is not, is before, is on or before, is after, is on or after> <a specific date>. But what if I want to do something like <a date> <is in the last, is in the next> <user-entered number> <seconds, minutes, hours, days, weeks>? Is there a way to do relative date comparison? The answer is “yes”, but this is going to take a lot of explanation. So buckle up, and let’s dive right in!

The Problems

There are two major problems to overcome when doing relative date comparison and integrating that with NSPredicateEditorRowTemplate:

NSPredicateEditor compacts left expressions into a unique list. Where a left expression supports multiple operators, those are also uniqued. In other words, you can’t do both myKeyPath = <a value form a textfield> and myKeyPath = <a value from a popup> in the same NSPredicateEditor. It doesn’t matter if these are defined in different row templates. NSPredicateEditor will still find both of them, and won’t know what to display when the user chooses myKeyPath from the first popup and = from the second popup. What should it display? A textfield? A popupmenu? We care about this because if we want to support both myDate <is after> <a specific date> and myDate <is in the last> <number> <time unit>, these both boil down to the same thing (after doing dynamic date resolution): find if one date is after another date. In other words, the same left expression, the same operator, but different right expressions. NSPredicateEditor doesn’t support this. We need to find a way around this.
NSPredicate doesn’t have any obvious date addition or date subtraction features. We need to figure out how to add and subtract arbitrary time intervals from arbitrary dates.

The Solutions

While these may seem like road-blocker problems, they’re really not too bad.

Solving the operator problem

The key to tricking NSPredicateEditor into showing different right expressions for two operators that are fundamentally the same is to not use the same operator. These are the operators that NSPredicateEditor recognizes:

typedef enum {
   NSLessThanPredicateOperatorType = 0,
   NSLessThanOrEqualToPredicateOperatorType,
   NSGreaterThanPredicateOperatorType,
   NSGreaterThanOrEqualToPredicateOperatorType,
   NSEqualToPredicateOperatorType,
   NSNotEqualToPredicateOperatorType,
   NSMatchesPredicateOperatorType,
   NSLikePredicateOperatorType,
   NSBeginsWithPredicateOperatorType,
   NSEndsWithPredicateOperatorType,
   NSInPredicateOperatorType,
   NSCustomSelectorPredicateOperatorType,
   NSContainsPredicateOperatorType,
   NSBetweenPredicateOperatorType
} NSPredicateOperatorType;

You’ll notice that only six of 14 operators are for numeric comparisons (<, <=, >, >=, =, !=). The rest are for string comparisons. This means we have 7 or 8 operators that are sitting around unused when we’re doing a numeric comparison (and date comparisons are really numeric comparisons).

The other key to tricking NSPredicateEditor into showing different right expressions is to realize that NSPredicateEditor is just a UI. It doesn’t care what the actual underlying NSPredicate is. It’s just going to show whatever it’s given, even if that is different from the actual NSPredicate.

So the solution:

#define NSInTheLastPredicateOperatorType NSMatchesPredicateOperatorType
#define NSInTheNextPredicateOperatorType NSLikePredicateOperatorType

That’s it. Any time we want to show an “in the last”-style right expression, we’re going to tell the editor “this is the ‘matches’” operator. Then we’re just going to do a bit of handling in code to not actually use the matches operator, but the proper comparator instead. Simple!

Solving the relative date problem

Have you ever looked at how dates are represented in predicates? It’s quite interesting:

NSDate * d = [NSDate date];
NSLog(@"%@", [NSPredicate predicateWithFormat:@"%@ != 0", d]);
//logs "CAST(312333057.230785, "NSDate") != 0"

Well now, that’s curious. We’re taking some number and “casting” it as an NSDate. But what’s that number? Let’s do:

NSLog(@"%f", [d timeIntervalSinceReferenceDate]);
//logs "312333057.230785"

So this number is a time interval! This is very convenient. But what about all this casting? If we capture the left expression of this predicate, we will find that it’s an NSExpression of type NSFunctionExpressionType, and that the -function of this expression is @"castObject:toType:". Further introspection reveals that the -arguments to this function are two NSExpressions: The first is a constant value expression holding an NSNumber, whose -doubleValue is 312333057.230785, and the second is a constant value expression holding the string @"NSDate".

This is very important, because we learn 3 major things:

There is an undocumented function for NSExpression: castObject:toType:.
This function wants a number as its first argument
This function wants a string (that represents a class) as its second argument.

Armed with this information, we can surmise:

We can create predicates that have the string CAST() in them. We don’t have to rely on predicateWithFormat: to insert that for us.
Any number, or any function that results in a number, can be used as the first parameter to a CAST() function and be cast to an NSDate. That number represents a time interval since the first instant of 1 January 2001, GMT (the reference date).
We can cast objects to other kinds of classes

Let’s test each one of these things:

NSPredicate * p = [NSPredicate predicateWithFormat:@"%@ > CAST(0, 'NSDate')", [NSDate date]];
NSLog(@"%d", [p evaluateWithObject:nil]);  //logs "1".  right now is after our reference date!

p = [NSPredicate predicateWithFormat:@"%@ > CAST(1+2+3+4+5+6, 'NSDate')", [NSDate date]];
NSLog(@"%d", [p evaluateWithObject:nil]);  //logs "1".  right now is after 21 seconds after the reference date!

p = [NSPredicate predicateWithFormat:@"CAST(%@, 'NSNumber') > 0", [NSDate date]];
NSLog(@"%d", [p evaluateWithObject:nil]);  //logs "1". We can cast dates to their numerical equivalent!

So all three of our assumptions appear to be correct! The last one is the most interesting, however. If we pull out the leftExpression of the predicate and evaluate it, we get 312333057.230785. In other words, casting a date to a number simply converts it to its reference date time interval! Since we could cast a number to a date, it makes perfect sense that we can cast a date to a number.

The last trick is “how do we get the current date without having to substitute it in every time?”. Fortunately, there’s a very simple answer: now(). now() is one of the built-in functions supported by NSExpression, and it (conveniently enough) returns an NSDate representing the current date and time.

Now that we know this, we can construct relative date predicates! So for example, let’s do “someDate is in the last 30 days”. If a date is in the last 30 days, that means that someDate is after now - 30 days:

[NSPrediate predicateWithFormat:@"someDate > CAST(CAST(now(), 'NSNumber') - %d, 'NSDate')", (30*86400)];

Working from the inside-out, we have:

now() - retrieve the current NSDate
CAST(now(), 'NSNumber') - convert the current date into an NSNumber
CAST(now(), 'NSNumber') - %d - subtract a time interval from the current timestamp. This difference must be in seconds. 30*86400 is 30 days in seconds (there are 86,400 seconds in a day)
CAST(CAST(now(), 'NSNumber') - %d, 'NSDate') - once we’ve done our subtraction, cast the time interval back to an NSDate

At this point, we can compare it against our target date. We could’ve done the date subtraction on the value returned by the left expression, but there are some circumstances where that’s not a good idea (primarily when integrating with CoreData), so we’ll keep it in the right.

Voilà! Date subtraction in an NSPredicate! Doing something like “<some date> is during <this week, this month, this year>” would be slightly more complex (it would involve a BETWEEN comparison [or something functionally identical]), but still do-able. Even more fun would be a predicate of the form “<some date> is during the <day, week, month, year> of <another date>”. Also very difficult, but again not impossible. Maybe we’ll do those in another post. Anyway…

The Row Template

Our row template is going to be very similar to the template in my earlier post, because (again) we’re doing NSTimeInterval manipulations. Let’s get started:

The Interface

@interface DDRelativeDateRowTemplate : NSPredicateEditorRowTemplate {
    NSPopUpButton * unitPopUpButton;
}

- (id) initWithLeftExpressions:(NSArray *)leftExpressions;

@end

Nothing new to see here.

The Implementation

#define NSInTheLastPredicateOperatorType NSMatchesPredicateOperatorType
#define NSInTheNextPredicateOperatorType NSLikePredicateOperatorType

Some #defines to make things a bit more readable in our code

@implementation DDRelativeDateRowTemplate

- (id) initWithLeftExpressions:(NSArray *)leftExpressions {
    NSAttributeType rightType = NSDoubleAttributeType; //NSTimeInterval is a typedef'd double
    NSComparisonPredicateModifier modifier = NSDirectPredicateModifier; //don't need "ANY" or "ALL"
    NSArray * operators = [NSArray arrayWithObjects:
                           [NSNumber numberWithUnsignedInteger:NSInTheLastPredicateOperatorType],
                           [NSNumber numberWithUnsignedInteger:NSInTheNextPredicateOperatorType],
                           nil];
    NSUInteger options = 0;
    return [super initWithLeftExpressions:leftExpressions
             rightExpressionAttributeType:rightType
                                 modifier:modifier
                                operators:operators
                                  options:options];
}

Our init method is almost identical to the init method in our previous template, with the exception that this time we’re only supporting 2 operators. Notice that we’re telling the predicate editor that these are the “matches” and “like” operators. Again, this is only to get around problem #1 (see above).

static NSString * unitNames[] = {@"seconds", @"minutes", @"hours", @"days", @"weeks"};
static NSInteger unitIntervals[] = {1, 60, 3600, 86400, 604800};
#define numberOfUnits() (sizeof(unitNames)/sizeof(unitNames[0]))

- (NSPopUpButton *) unitPopUpButton {
    if (unitPopUpButton == nil) {
        unitPopUpButton = [[NSPopUpButton alloc] initWithFrame:NSZeroRect pullsDown:NO];

        NSMenu * unitMenu = [unitPopUpButton menu];
        for (int i = 0; i < numberOfUnits(); ++i) {
            [unitMenu addItemWithTitle:unitNames[i] action:NULL keyEquivalent:@""];
        }
    }
    return unitPopUpButton;
}

- (void) dealloc {
    [unitPopUpButton release];
    [super dealloc];
}

- (void) getBase:(NSTimeInterval *)base unit:(NSInteger *)unit fromTimeInterval:(NSTimeInterval)timeInterval {
    if (base == nil || unit == nil) {
        [NSException raise:NSInvalidArgumentException format:@"base and unit cannot be nil"];
    }

    for (NSInteger unitIndex = numberOfUnits() - 1; unitIndex >= 0; unitIndex--) {
        if (timeInterval >= unitIntervals[unitIndex]) {
            *base = timeInterval / unitIntervals[unitIndex];
            *unit = unitIndex;
            return;
        }
    }
}

- (NSTimeInterval) timeIntervalFromBase:(NSTimeInterval)base unit:(NSInteger)unitIndex {
    if (unitIndex >= numberOfUnits()) {
        [NSException raise:NSInvalidArgumentException format:@"unitIndex beyond max allowed bounds (%d)", numberOfUnits()];
        return 0;
    }

    return (base * unitIntervals[unitIndex]);
}

This code is identical to the code that was in our previous template, so I won’t explain it here.

- (NSArray *) templateViews {
    NSMutableArray * views = [[super templateViews] mutableCopy];

    [views addObject:[self unitPopUpButton]];

    NSPopUpButton * operatorView = [views objectAtIndex:1];
    [[operatorView itemAtIndex:0] setTitle:@"is in the last"];
    [[operatorView itemAtIndex:1] setTitle:@"is in the next"];

    return [views autorelease];
}

Our -templateViews method is almost the same, except that we’re altering the title of of the operators. If we were to leave out that bit, then we would see “matches” and “is like” in the interface. By changing the title here, we’re providing a new default value for the operator title. Note that this can be changed via localization, and more importantly, your NSLocalizedString macros for generating the strings file should use the values listed here, not the “matches” and “is like” values. Also note that operators show up in the interface in the same order in which they’re given in the -init method.

- (double) matchForPredicate:(NSPredicate *)predicate {
    if (![predicate isKindOfClass:[NSComparisonPredicate class]]) { goto errorExit; }

    NSComparisonPredicate * comparison = (NSComparisonPredicate *)predicate;

    NSExpression * left = [comparison leftExpression];
    if (![[self leftExpressions] containsObject:left]) { goto errorExit; }

    NSPredicateOperatorType operator = [comparison predicateOperatorType];
    if (operator != NSGreaterThanPredicateOperatorType && operator != NSLessThanPredicateOperatorType) { goto errorExit; }

    NSExpression * right = [comparison rightExpression];
    if ([right expressionType] != NSFunctionExpressionType) { goto errorExit; }
    if (![[right function] isEqual:@"castObject:toType:"]) { goto errorExit; }

    NSArray * outerCastArguments = [right arguments];
    //we can pull these out without bounds checking because a CAST() function *must* have 2 arguments

    NSExpression * firstArgument = [outerCastArguments objectAtIndex:0];
    {
        //the first argument must be either an addition or subtraction function
        if ([firstArgument expressionType] != NSFunctionExpressionType) { goto errorExit; }
        if (![[firstArgument function] isEqual:@"add:to:"] && ![[firstArgument function] isEqual:@"from:subtract:"]) { goto errorExit; }
        NSArray * relativeArguments = [firstArgument arguments];
        NSExpression * firstRelativeArgument = [relativeArguments objectAtIndex:0];
        {
            if ([firstRelativeArgument expressionType] != NSFunctionExpressionType) { goto errorExit; }
            if (![[firstRelativeArgument function] isEqual:@"castObject:toType:"]) { goto errorExit; }
            NSArray * innerCastArguments = [firstRelativeArgument arguments];
            NSExpression * firstInnerArgument = [innerCastArguments objectAtIndex:0];
            if ([firstInnerArgument expressionType] != NSFunctionExpressionType) { goto errorExit; }
            if (![[firstInnerArgument function] isEqual:@"now"]) { goto errorExit; }

            NSExpression * secondInnerArgument = [innerCastArguments objectAtIndex:1];
            if ([secondInnerArgument expressionType] != NSConstantValueExpressionType) { goto errorExit; }
            if (![[secondInnerArgument constantValue] isEqual:@"NSNumber"]) { goto errorExit; }
        }

        NSExpression * secondRelativeArgument = [relativeArguments objectAtIndex:1];
        {
            //the second relative argument is the actual relative difference, so it must be an NSNumber
            if ([secondRelativeArgument expressionType] != NSConstantValueExpressionType) { goto errorExit; }
            if (![[secondRelativeArgument constantValue] isKindOfClass:[NSNumber class]]) { goto errorExit; }
        }
    }

    NSExpression * secondArgument = [outerCastArguments objectAtIndex:1];
    {
        if ([secondArgument expressionType] != NSConstantValueExpressionType) { goto errorExit; }
        if (![[secondArgument constantValue] isEqual:@"NSDate"]) { goto errorExit; }
    }

    return DBL_MAX;

errorExit:
    return 0.0;
}

This is a beast of a method. This is how we determine if this row template recognizes a predicate or not. Basically what we’re doing here is making sure that the predicate has a extremely specific structure. If every requirement is met, then we return DBL_MAX, which is NSPredicateEditorRowTemplate’s way of saying “I match this predicate better than anyone else ever could”. When NSPredicateEditor finds that multiple row templates match a predicate, it uses the row template that returns the highest match value. DBL_MAX is just a cheap way of ensuring that no other template can handle this predicate.

The expected structure is as follows: (each box is an NSExpression, and downward arrows indicate arguments to a function expression)

And yes, I use goto all over the place in that code. Deal with it.

- (NSPredicate *) predicateWithSubpredicates:(NSArray *)subpredicates {
    NSPredicate * predicate = [super predicateWithSubpredicates:subpredicates];
    if ([predicate isKindOfClass:[NSComparisonPredicate class]]) {
        NSComparisonPredicate * comparison = (NSComparisonPredicate *)predicate;

        NSExpression * right = [comparison rightExpression];
        NSNumber * value = [right constantValue];

        NSInteger unit = [[self unitPopUpButton] indexOfSelectedItem];

        NSTimeInterval newInterval = [self timeIntervalFromBase:[value doubleValue] unit:unit];
        value = [NSNumber numberWithDouble:newInterval];
        right = [NSExpression expressionForConstantValue:value];

        //default values are for NSInTheLastPredicateOperatorType
        NSString * function = @"from:subtract:";
        NSPredicateOperatorType newOperator = NSGreaterThanPredicateOperatorType;

        if ([comparison predicateOperatorType] == NSInTheNextPredicateOperatorType) {
            function = @"add:to:";
            newOperator = NSLessThanPredicateOperatorType;
        }

        //"now()" is a function and takes no arguments
        NSExpression * now = [NSExpression expressionForFunction:@"now" arguments:[NSArray array]];

        //CAST(now(), 'NSNumber')
        NSArray * castNowArguments = [NSArray arrayWithObjects:now, [NSExpression expressionForConstantValue:@"NSNumber"], nil];
        NSExpression * castNow = [NSExpression expressionForFunction:@"castObject:toType:" arguments:castNowArguments];

        //CAST(now(), 'NSNumber') [+/-] {a time interval}
        NSArray * relativeTimestampArguments = [NSArray arrayWithObjects:castNow, right, nil];
        NSExpression * relativeTimestamp = [NSExpression expressionForFunction:function arguments:relativeTimestampArguments];

        //CAST(CAST(now(), 'NSNumber') [+/-] {a time interval}, 'NSDate')
        NSArray * castToDateArguments = [NSArray arrayWithObjects:relativeTimestamp, [NSExpression expressionForConstantValue:@"NSDate"], nil];
        NSExpression * castToDate = [NSExpression expressionForFunction:@"castObject:toType:" arguments:castToDateArguments];

        predicate = [NSComparisonPredicate predicateWithLeftExpression:[comparison leftExpression] 
                                                       rightExpression:castToDate 
                                                              modifier:[comparison comparisonPredicateModifier] 
                                                                  type:newOperator 
                                                               options:[comparison options]];
    }
    return predicate;
}

This method is similar in principle to its counterpart in our earlier row template. Here we’re letting super give us a predicate that contains what the user entered into the interval field, and then we extract that number, convert it to an absolute time interval, and then re-create the right expression of the comparison predicate. We create the expression manually to ensure that the structure returned here exactly matches the structure expected by -matchForPredicate:. Notice that we’re changing our matches and like operators to the expected less than and greater than versions.

- (void) setPredicate:(NSPredicate *)predicate {
    if ([predicate isKindOfClass:[NSComparisonPredicate class]]) {
        NSComparisonPredicate * comparison = (NSComparisonPredicate *)predicate;
        /**
         I know that to get here, I must have matched the predicate.
         Therefore I can drill into the comparison predicate structure with reckless abandon!
         **/
        NSExpression * right = [comparison rightExpression];
        NSArray * arguments = [right arguments];

        //this expression is our addition or subtraction function
        NSExpression * relative = [arguments objectAtIndex:0];

        //the second argument to our relative function is our absolute time interval
        NSExpression * intervalExpression = [[relative arguments] objectAtIndex:1];
        NSNumber * interval = [intervalExpression constantValue];

        NSTimeInterval base = 0;
        NSInteger unit = 0;
        [self getBase:&base unit:&unit fromTimeInterval:[interval doubleValue]];

        [[self unitPopUpButton] selectItemAtIndex:unit];

        NSExpression * newRight = [NSExpression expressionForConstantValue:[NSNumber numberWithDouble:base]];
        NSPredicateOperatorType newOperator = NSInTheLastPredicateOperatorType;
        if ([comparison predicateOperatorType] == NSLessThanPredicateOperatorType) {
            newOperator = NSInTheNextPredicateOperatorType;
        }

        predicate = [NSComparisonPredicate predicateWithLeftExpression:[comparison leftExpression] 
                                                       rightExpression:newRight
                                                              modifier:[comparison comparisonPredicateModifier] 
                                                                  type:newOperator 
                                                               options:[comparison options]];
    }
    [super setPredicate:predicate];
}

@end

And finally! When given a predicate, we need to reflect those values in the UI. Here we’re simply going to extract the absolute time interval that’s buried in the rightExpression and use it to figure out what our base and unit should be. We also change the operator from greater than or less than to likes or matches, simply so that the operator popup shows the right value. After that, we re-package things, and send it on up to super.

Wrap-up

Not too bad, eh? Grokking this involves a little bit of mental gymnastics, but if you’re familiar with predicates and their internal structure, most of this code should be really straight-forward. This was mainly to help connect all those disparate dots and form a coherent picture. The more you play with these row templates, the more you’ll truly understand how they interact with each other and their parent predicate editor. They’re quite clever little classes, and they can really make our apps that much more “Mac-like”.

Mathematically evaluating NSStrings

Mon, 22 Nov 2010 21:01:24 -0800

I’ve recently posted the code to a project I’ve written called DDMathParser. It’s a way whereby you can take an NSString and evaluate it as a mathematical expression. For example, you can do:

NSLog(@"%@", [@"1 + 3 * 4 - 5" numberByEvaluatingString]); //logs "8"

There are several other ways to evaluate strings, including methods that allow you to use variables (1 + $a, and then substitute $a for a value later). You can even define custom functions, like mySuperSecretFunction(42).

This was a really fun project, because there were some really interesting challenges to work around (like how can I parse a left associative expression using a recursive descent parser without getting caught in an infinite recursion?). I’ll save those for another post.

For now, go check out the source on github and let me know what you think!

http://github.com/davedelong/DDMathParser

Creating a simple NSPredicateEditorRowTemplate

Sun, 21 Nov 2010 23:00:46 -0800

NSPredicateEditor is a great class, provided you figure out how it works. There’s a fair amount of documentation as to what’s going on, but if you ever want to do something beyond what’s possible through configuration in Interface Builder, you’re probably going to spend several hours playing with things until you get it right.

Hopefully, I can help cut down that time.

What’s going on under the hood

NSPredicateEditor is a subclass of NSRuleEditor. However, they really don’t behave the same way at all, so knowing that doesn’t really give you much insight (that I’ve found).

NSPredicateEditor uses a template mechanism for displaying an NSPredicate. These templates are instances of NSPredicateEditorRowTemplate (go figure). Each row template (with one exception) displays a single NSComparisonPredicate.

The exception to this is the built-in row template for handling NSCompoundPredicates. We’re going to ignore this template in this post and focus on customizing templates for comparison predicates.

When the NSPredicateEditor gets a new predicate object (via -setObjectValue:), it has to figure out what row templates it needs. It’s a pretty simple process: The editor simply asks each one of its row templates whether it recognizes the NSPredicate. (-matchForPredicate:) If the template responds affirmatively, then the editor will -copy the template (this is why row templates conform to <NSCopying>) and invoke -setPredicate:.

-setPredicate: is simply going to extract the predicate’s leftExpression, predicateOperatorType, and rightExpression. These values will then be set into the UI.

The UI

One of the interesting things about row templates is that they do not inherit from NSView. In other words, the actual NSPredicateEditorRowTemplate object is never (indeed cannot be) displayed to the user. So what is it the user is seeing? It’s the row template’s -templateViews.

By default, an NSPredicateEditorRowTemplate provides 3 template views: an NSPopUpButton, a second NSPopUpButton, and either a third NSPopUpButton or some sort of user-interactable view, like an NSDatePicker or an NSTextField. The first popup lists all of the possible left-hand NSExpressions, the second holds the operators, and the third view holds the right-hand NSExpressions.

These views are received by the NSPredicateEditor and shown in the UI. Their styles are manipulated to make them have the “rounded rect” appearance, and their frames are changed to make them fit in the row. The main attribute that’s useful to configure is the frame width of the right-hand view. If the third view is an NSDatePicker, you may alter the width of the view to allow room for specifying a time in addition to the date. (By default, an NSDatePicker only allows date selection)

Customizing the UI is a simple matter of overriding the -templateViews method:

- (NSArray *) templateViews {
  NSMutableArray * templateViews = [[super templateViews] mutableCopy];

  //at this point, you have a mutable array of views.
  //you can add views, remove views, alter appropriate properties of existing views, etc.

  return [templateViews autorelease];
}

However, you need to be careful with this. -templateViews is called more than once, so if you’re instantiating a new view each time this is invoked, you may end up allocating too many views and not know which one is actually being shown on the UI. For this reason I prefer a “lazy allocation” method:

- (NSView *) myExtraView {
  if (myExtraView == nil) {
    myExtraView = [[MyExtraView alloc] init...];
    ...
  }
  return myExtraView;
}

- (NSArray *) templateViews {
  NSMutableArray * templateViews = [[super templateViews] mutableCopy];

  [templateViews addObject:[self myExtraView]];

  return [templateViews autorelease];
}

Now I know that the myExtraView object will only be allocated once per instance of my row template, and I can always go access the view directly to retrieve information about what the user has manipulated.

If you’re localizing this NSPredicateEditor, then you must consider this:

When specifying the translated value of a row template, the number of positional specifiers in the translated value must be equal to the number of views returned from -templateViews. If not, the editor will fail to localize that row.

In other words, if you have a custom -templateViews method that adds a fourth view, then your translated string for this row must have %1$@, %2$@, %3$@, and %4$@ (with the translated values interspersed appropriately). %1$@ will be replaced with the first view in the array returned from -templateViews, %2$@ will be replaced with the second view, etc.

</caution>

On a final point regarding -templateViews, I’ve found that I rarely have an occasion to alter the first or second views returned by super. Your mileage may vary, but I’ve generally found that it’s best to leave them alone.

Building a custom row template

Now that we understand the basics of what’s going on, let’s build a simple NSPredicateEditorRowTemplate. To keep things simple, we’re going to build a row template that allows us to compare against an NSTimeInterval.

The Interface

@interface DDTimeIntervalRowTemplate : NSPredicateEditorRowTemplate {
    NSPopUpButton * unitPopUpButton;
}

- (id) initWithLeftExpressions:(NSArray *)leftExpressions;

@end

It’s pretty simple. We inherit from NSPredicateEditorRowTemplate, we provide a custom initializer (since we’ll be instantiating the template programmatically), and we have one instance variable for holding on to our extra NSPopUpButton.

The Implementation

@implementation DDTimeIntervalRowTemplate

- (id) initWithLeftExpressions:(NSArray *)leftExpressions {
    NSAttributeType rightType = NSDoubleAttributeType; //NSTimeInterval is a typedef'd double
    NSComparisonPredicateModifier modifier = NSDirectPredicateModifier; //don't need "ANY" or "ALL"
    NSArray * operators = [NSArray arrayWithObjects:
                           [NSNumber numberWithUnsignedInteger:NSLessThanPredicateOperatorType],
                           [NSNumber numberWithUnsignedInteger:NSLessThanOrEqualToPredicateOperatorType],
                           [NSNumber numberWithUnsignedInteger:NSGreaterThanPredicateOperatorType],
                           [NSNumber numberWithUnsignedInteger:NSGreaterThanOrEqualToPredicateOperatorType],
                           [NSNumber numberWithUnsignedInteger:NSEqualToPredicateOperatorType],
                           [NSNumber numberWithUnsignedInteger:NSNotEqualToPredicateOperatorType],
                           nil];
    NSUInteger options = 0;
    return [super initWithLeftExpressions:leftExpressions
             rightExpressionAttributeType:rightType
                                 modifier:modifier
                                operators:operators
                                  options:options];
}

Again, this should be fairly straight-forward. We’re creating a row template with the left expressions given to the initializer. These left expressions will be compared against a user-entered double value. We’ll be doing a direct comparison (simply put: <left expression> <comparison operator> <user-entered value>), and we’re supporting the standard numeric operators: <, <=, >, >=, =, and !=. The options bit is only useful for string comparison (it’s how you specific case insensitivity or diacritic insensitivity, etc). Once we’ve got everything specified, we’ll let super’s initializer finish everything off for us.

Continuing…

static NSString * unitNames[] = {@"seconds", @"minutes", @"hours", @"days", @"weeks"};
static NSInteger unitIntervals[] = {1, 60, 3600, 86400, 604800};
#define numberOfUnits() (sizeof(unitNames)/sizeof(unitNames[0]))

- (NSPopUpButton *) unitPopUpButton {
    if (unitPopUpButton == nil) {
        unitPopUpButton = [[NSPopUpButton alloc] initWithFrame:NSZeroRect pullsDown:NO];

        NSMenu * unitMenu = [unitPopUpButton menu];
        for (int i = 0; i < numberOfUnits(); ++i) {
            [unitMenu addItemWithTitle:unitNames[i] action:NULL keyEquivalent:@""];
        }
    }
    return unitPopUpButton;
}

- (void) dealloc {
    [unitPopUpButton release];
    [super dealloc];
}

This method will be our lazy initializer for our unit popup button (to ensure that we only allocate one button per instance of the row template). The button has 5 items in its menu, each representing a different unit of time measurement. We also have a static NSInteger array that reflects the number of seconds in each unit (ie, one day is 86,400 seconds).

One thing that’s interesting here is that we’re initializing our NSPopUpButton with NSZeroRect. We can do this because NSPredicateEditor will adjust the origin of the view to be in the appropriate spot relative to the other views and the size to fit the content. In other words, the frame will be taken care of for us.

And of course, since we’ve allocated an object, we must be sure to release it in our -dealloc method.

- (void) getBase:(NSTimeInterval *)base unit:(NSInteger *)unit fromTimeInterval:(NSTimeInterval)timeInterval {
    if (base == nil || unit == nil) {
        [NSException raise:NSInvalidArgumentException format:@"base and unit cannot be nil"];
    }

    for (NSInteger unitIndex = numberOfUnits() - 1; unitIndex >= 0; unitIndex--) {
        if (timeInterval >= unitIntervals[unitIndex]) {
            *base = timeInterval / unitIntervals[unitIndex];
            *unit = unitIndex;
            return;
        }
    }
}

- (NSTimeInterval) timeIntervalFromBase:(NSTimeInterval)base unit:(NSInteger)unitIndex {
    if (unitIndex >= numberOfUnits()) {
        [NSException raise:NSInvalidArgumentException format:@"unitIndex beyond max allowed bounds (%d)", numberOfUnits()];
        return 0;
    }

    return (base * unitIntervals[unitIndex]);
}

These 2 methods are simply convenience methods. The first method will convert an NSTimeInterval into a unit and a base. For example, if given 172800 as the interval, it will return a base of 2 and a unit of 3, to represent 2 days.

The second method is simply the inverse. Given a base and a unit, it will turn it into an absolute NSTimeInterval.

Now for the fun stuff!

- (NSArray *) templateViews {
    NSMutableArray * views = [[super templateViews] mutableCopy];

    [views addObject:[self unitPopUpButton]];

    return [views autorelease];
}

This is about as simple as it gets. When we’re asked for what views to display in the interface, we’re going to return the three views provided by super (two popup buttons and an NSTextField) and add a fourth button of our own (the popup button denoting a unit of time).

- (NSPredicate *) predicateWithSubpredicates:(NSArray *)subpredicates {
    NSPredicate * p = [super predicateWithSubpredicates:subpredicates];
    if ([p isKindOfClass:[NSComparisonPredicate class]]) {
        NSComparisonPredicate * comparison = (NSComparisonPredicate *)p;

        NSExpression * right = [comparison rightExpression];
        NSNumber * value = [right constantValue];

        NSInteger unit = [[self unitPopUpButton] indexOfSelectedItem];

        NSTimeInterval newInterval = [self timeIntervalFromBase:[value doubleValue] unit:unit];
        value = [NSNumber numberWithDouble:newInterval];
        right = [NSExpression expressionForConstantValue:value];

        p = [NSComparisonPredicate predicateWithLeftExpression:[comparison leftExpression] 
                                               rightExpression:right 
                                                      modifier:[comparison comparisonPredicateModifier] 
                                                          type:[comparison predicateOperatorType] 
                                                       options:[comparison options]];
    }
    return p;
}

This method is one of the two at the heart of our custom template. Via this method, we’re translating what’s on the UI into an NSPredicate. For the most part, we’re going to let super handle the implementation, with one minor alteration. By invoking super on this, we’re going to get back an NSPredicate of the form <left expression> <operator> <value of textfield>. We need to extract the rightExpression, who’s constantValue will be an NSNumber representing what was in the textfield. It is the doubleValue of this NSNumber that becomes the base, and the index of our unitPopUpButton is our unit. Once we have those two values, we can run them through our conversion method, then rebuild our comparison predicate. This new comparison predicate will be exactly the same as the predicate returned by super, with the single change of having the constantValue of the rightExpression modified.

Finally…

- (void) setPredicate:(NSPredicate *)newPredicate {
    if ([newPredicate isKindOfClass:[NSComparisonPredicate class]]) {

        NSComparisonPredicate * comparison = (NSComparisonPredicate *)newPredicate;

        NSExpression * right = [comparison rightExpression];
        NSNumber * value = [right constantValue];

        NSTimeInterval base = 0;
        NSInteger unit = 0;
        [self getBase:&base unit:&unit fromTimeInterval:[value doubleValue]];

        value = [NSNumber numberWithDouble:base];
        right = [NSExpression expressionForConstantValue:value];

        [[self unitPopUpButton] selectItemAtIndex:unit];

        newPredicate = [NSComparisonPredicate predicateWithLeftExpression:[comparison leftExpression] 
                                                          rightExpression:right 
                                                                 modifier:[comparison comparisonPredicateModifier] 
                                                                     type:[comparison predicateOperatorType] 
                                                                  options:[comparison options]];
    }

    [super setPredicate:newPredicate];
}

@end

This is the final method that we need to implement. This method will take an NSPredicate and extract various values from it to reflect in the UI. Like its inverse -predicateWithSubpredicates:, we’re going to let super handle most of the work. However, we need to do a bit of manipulation first. We’re going to extract the constantValue of the comparison predicate’s rightExpression. This NSNumber is the absolute time interval, in seconds. We’re going to take that time interval and run it through our conversion method to turn it into a base and a unit. The unit is used to select the appropriate item in the unitPopUpButton, and the base is put back into the NSPredicate. When we pass this new predicate up to super, the base will be placed inside the text field (the third view returned from -templateViews).

Using this template

Now that we have this template, we have to actually use it. Fortunately, it’s pretty simple:

NSPredicateEditor * editor = ...; //some NSPredicateEditor. perhaps an IBOutlet?
NSMutableArray * rowTemplates = [[editor rowTemplates] mutableCopy];

NSArray * leftExpressions = [NSArray arrayWithObject:[NSExpression expressionForKeyPath:@"duration"]];
DDTimeIntervalRowTemplate * intervalTemplate = [[DDTimeIntervalRowTemplate alloc] initWithLeftExpressions:leftExpressions];
[rowTemplates addObject:intervalTemplate];
[intervalTemplate release];

[editor setRowTemplates:rowTemplates];
[rowTemplates release];

This should be fairly easy to understand. We’re simply adding an instance of DDTimeIntervalRowTemplate to the list of templates available to our NSPredicateEditor. This row template recognizes one left expression, the keyPath @"duration". This means that all predicates generated by this row template will be of the form duration <operator> <time interval>. Pretty easy.

Localizing this template

To localize this row template, we’ll need the following somewhere in a comment:

NSLocalizedStringFromTable(@"%[duration]@ %[is, is not, is greater than, is less than, is greater than or equal to, is less than or equal to]@ %@ %[seconds, minutes, hours, days, weeks]@", @"Predicate", @"the text of the duration template")

This will generate a rather lengthy strings file (30 different key-value pairs), with each value having four positional specifiers (as was mentioned above), one for each of the views returned from -templateViews. For a more complete explanation of how localizing a predicate editor, see my earlier post on that very topic.

Wrap-Up

So there you have it! This may be a rather simple and contrived example, but a useful one. Hopefully this will help you as you wrap your brain around NSPredicateEditor and its supporting classes. There are still a couple gotchas, but we’ll learn about those in another post.

Abusing NSPredicate

Fri, 12 Nov 2010 09:31:27 -0800

NSPredicate is a nifty class. It’s intended use is to be an objected-oriented way of expressing a truth statement. We see this being used with things like -[NSArray filteredArrayUsingPredicate:], -[NSFetchRequest setPredicate:], and more. NSPredicate, however, can offer us a lot more.

There are 2 things that make NSPredicate so insanely awesome:

Its string parser
The evaluation power of NSExpression (one of NSPredicate’s support classes)

NSPredicate Parsing

One of the best things about NSPredicate is its parsing engine. Given a well-formatted NSString, NSPredicate will turn it into a tree of NSCompoundPredicate and NSComparisonPredicate objects. This can be used to our advantage. If we have a string that represent some boolean expression, we can tap NSPredicate to parse it for us and give us back an organized syntax tree.

For this example, let’s consider the following:

(a | b) & c | (b | d)

If we just try to run this through the predicate parser, we’ll get an exception, for 2 reasons:

A predicate is a truth statement. This expression is simply a value. It is not being compared to anything, and as such does not represent a true or false statement, but simply a value.
Each sub-expression of a predicate must itself be a predicate. Since “c” (for example) is not being compared to anything, it is not a valid statement.

Fixing the first problem is easy. We can just tack “= 0” onto the end of the statement:

(a | b) & c | (b | d) = 0

As for fixing the second, we can do that with a little bit of find-and-replace by regular expression. For simplicity, we’ll say that each one of these identifiers (a, b, c, and d) must be alphanumeric. We can then use something like NSRegularExpression (on iOS) or RegexKit (on Mac) to replace “([a-z0-9]+)” with “\1 = 0”, thereby giving us:

(a = 0 | b = 0) & c = 0 | (b = 0 | d = 0) = 0

We can now run this through +[NSPredicate predicateWithFormat:] to get our parsed tree. From there you can recursively walk the tree and manipulate things as much as you like.

NSExpression Solving

Let’s say you have a string that contains some sort of mathematical statement. Perhaps it’s user-entered, or perhaps it’s dynamically generated. For our purposes, we’re going to use:

22/7.0 + (13*42) - 1024

Our calculator shows us that we should be getting -474.857142857142857 as the result.

But how can we evaluate this dynamically? Well, you could use something like Graham Cox’s excellent GCMathParser to parse and evaluate it, but this has a limitation: it’s a bit difficult (read: nearly impossible) to extend to use functions not supported by the parser.

Fortunately, we can abuse NSPredicate to do the work for us.

NSPredicate has a wonderful parsing engine (which we’ve already abused), and it builds a tree built out of NSExpression objects, which have this wonderful method called -expressionValueWithObject:context: which will evaluate everything for us. Unfortunately, there’s no way to build an NSExpression tree out of an arbitrary NSString. However, NSPredicate can.

So we just need to make out statement into a predicate, run it through the parser, and extract the appropriate value! This is really simple. To make something into a predicate, we simply need to add an operator and a comparison value:

22/7.0 + (13*42) - 1024 = 0

Now, we can pump it through NSPredicate:

NSPredicate * parsed = [NSPredicate predicateWithFormat:@"22/7.0 + (13*42) - 1024 = 0"];

We know that this is an NSComparisonPredicate (since it’s of the form <expression> <operator> <expression>), so we can simply extract the leftExpression:

NSExpression * left = [(NSComparisonPredicate *)parsed leftExpression];

And finally, we can now evaluate it:

NSNumber * result = [left expressionValueWithObject:nil context:nil];
NSLog(@"result: %@", result);

Wonderfully, this logs -474.8571428571429, which is exactly what we were hoping for.

Defining custom key path operators

Tue, 09 Nov 2010 12:27:53 -0800

(This was prompted by a recent question on StackOverflow.)

Key-value coding is one of my more favorite things about Cocoa (up there with NSPredicate). Basically, it allows you to access properties of objects by name (ie, as a string) rather than invoking a method (er… sending a message) directly.

Along with accessing properties, you can (with some limitations) retrieve calculated values (not strictly properties) about these objects. For example:

NSArray * anArray = .... //an NSArray of NSNumbers 
NSNumber * count = [anArray valueForKeyPath:@"@count"];
NSNumber * max = [anArray valueForKeyPath:@"@max.self"];

There are several others, like @sum, @avg, and some collection-oriented operators. For a full list, see this page in the documentation.

But what if you want something else? What if you wanted to do something like @size, which we’ll define as the size (in bytes) that the object directly occupies in memory? To answer this question, let’s see if we can figure out what’s going on with NSArray, and take some clues from that.

#import <objc/runtime.h>

unsigned int methodCount = 0;
Method * methods = class_copyMethodList([NSArray class], &methodCount);
for (int i = 0; i < methodCount; ++i) {
  Method m = methods[i];
  NSLog(@"%@", NSStringFromSelector(method_getName(m)));
}
free(methods);

When we run this, we’re going to get a bunch of methods listed, but there are some interesting ones that should catch our eye:

_distinctUnionOfSetsForKeyPath:
_distinctUnionOfObjectsForKeyPath:
_distinctUnionOfArraysForKeyPath:
_unionOfSetsForKeyPath:
_unionOfArraysForKeyPath:
_unionOfObjectsForKeyPath:
_minForKeyPath:
_maxForKeyPath:
_countForKeyPath:
_avgForKeyPath:
_sumForKeyPath:

Those look familiar! Specifically, they look like our collection operators that have undergone a bit of string manipulation. It looks like the @ has been replaced with an _ and the string ForKeyPath: has been appended. (These methods also appear on NSSet)

So theoretically, if we just add a method that matches this format (_ + {nameOfKeyPath} + ForKeyPath:), it should work!

A bit more introspection reveals that these methods return an object, which makes sense because valueForKeyPath: also returns an object (id). We need to do the same.

Here we go (we’d need an identical category for NSSet):

#import <objc/runtime.h>

@interface NSArray (CustomKVCOperator)

- (id) _sizeForKeyPath:(NSString *)keyPath;

@end

@implementation NSArray (CustomKVCOperator)

- (id) _sizeForKeyPath:(NSString *)keyPath {
  id keyPathValue = [self valueForKeyPath:keyPath];
  size_t instanceSize = class_getInstanceSize([keyPathValue class]);
  return [NSNumber numberWithInt:instanceSize];
}

@end

Now we can test this:

NSArray * array = [NSArray array];
NSLog(@"size: %@", [array valueForKeyPath:@"@size.self"]); //logs "8"

It worked! (Honestly, the first time I tried this I was totally surprised that it did)

While this example is pretty contrived, it’s not difficult to imagine a scenario when it could be useful. Unfortunately, this only works on collections. You can’t (for example) add a _sqrtForKeyPath: method to NSNumber and hope to use @sqrt as a keyPath operator on NSNumber. Bummer. :(

As always with things like this, a word of caution: this works, but only because we rely on some undocumented behavior. This is by no means something that would get an app rejected from the App Stores, but be aware that Apple can change the implementation of valueForKeyPath: at any time.

A safer (albeit more complex) way to achieve this same functionality would be to subclass the appropriate collection (NSArray or NSSet) and override the valueForKeyPath: method. However, this introduces new problems, since both are class clusters, and subclassing a class cluster is fraught with peril.

At any rate, if you find yourself wishing that you had @stdDev or @productOfEveryThirdNumber operators, now you know.

Mike Ash: Creating Classes at Runtime

Fri, 05 Nov 2010 10:21:08 -0700

Mike Ash: Creating Classes at Runtime:

Another great article by Mike Ash that’s an expansion on my earlier article about dynamic subclassing.

Followup to Localizing NSPredicateEditor

Fri, 05 Nov 2010 09:42:36 -0700

To expand a little bit on my previous post, here’s a little bit more information:

If you ever forget the format to put in the NSLocalizedString() macros, you can do the following:

predicateEditor = ... //an NSPredicateEditor
NSData * stringsData = [predicateEditor _generateFormattingDictionaryStringsFile];
NSString * strings = [[NSString alloc] initWithData:stringsData encoding:NSUTF16StringEncoding];
[strings writeToFile:@"/path/to/Predicate.strings" encoding:NSUTF16StringEncoding error:nil];
[strings release];

This is relying on an undocumented method of NSPredicateEditor, but will work fine to simply generate the strings data. As always, you should probably not use this in shipping code (especially with the imminent launch of the Mac App Store).

The .strings file used by the NSPredicateEditor must not contain any other localizations. In other words, you must use the file for localizing only the editor. If you need to localize other parts of your application, their strings must be in a separate .strings file. (The sample, mentioned below, uses the NSLocalizedStringFromTable() macro to specify a custom strings file called Predicate.strings)
I’ve created an example project (which was the demo shown during my session at MacTech Conference 2010) to illustrate both creating a custom NSPredicateEditorRowTemplate and localizing the predicate editor. You can download it from my website: http://davedelong.com/portfolio
Most of what learned regarding localizing NSPredicateEditor was gleaned from this email thread and the linked sample project.

Localizing NSPredicateEditor

Thu, 04 Nov 2010 16:13:00 -0700

Many people who know me personally (at least as a developer), know something interesting about me: I love NSPredicate. I love it so much that I stood up and blathered for an hour on how awesome it is. I won’t go into that here.

One of the things that make NSPredicate superbly awesome is the NSPredicateEditor. NSPredicateEditor, in a nutshell, is a way to visually build an NSPredicate, if you take the time to really dig in and understand what’s going on. Unfortunately that’s somewhat difficult, since the documentation on NSPredicateEditor is sparse, to say the least.

Customizing NSPredicateEditorRowTemplates is do-able, though you’re going to spend a few hours of trial-and-error programming getting it to work properly. However, if you want to localize the predicate editor, you are up a creek without a paddle. There is absolutely no documentation on it.

So, here’s a paddle.

First off, some introduction: localizing an NSPredicateEditor is a bit more complex than you would expect, because it works by displaying more-or-less natural-language phrases to the user. Localizing buttons and labels is easy, because we deal with isolated words such as “View file” or “Space used:” and so on. However, when you want to localize a whole sentence, suddenly you have to starting thinking about things like word order and the placement of prepositions in relation to nouns and verbs, and a whole host of other interesting challenges.

To illustrate: In English, when we meet someone new, we usually ask “Where are you from?” To analyze just the order of words, we have: Adverb verb pronoun preposition. In Spanish, we would ask “¿De donde es?”. Literally this means “From where are you?” (We could say this in English and people understand us, but it’s uncommon). In Spanish, the phrase is almost exactly backwards: Preposition adverb verb (with implicit pronoun). If we had a different view for displaying the adverb, and one for displaying the verb and pronoun, and one for displaying the preposition, then we would have to worry about rearranging our views to make the sentence readable. Saying “¿Donde es de?” (Literally: Where are you from?) may make sense if we were to literally translate this to English, but to a native Spanish speaker, you’re speaking nonsense.

Unfortunately, this is the precise problem we face with NSPredicateEditor. In English we might say “A is equal to B”, but it’s easy to imagine another language requiring something that’s more like “A and B are equal”.

To translate this discrepancy into NSPredicate-speak, we have to deal with “leftValue operation rightValue” versus “leftValue rightValue operation”.

Fortunately, there is a way to deal with this, and it relies on understanding three things:

NSLocalizedString() and friends. I’m not going to cover this, since the documentation on how to localize is fairly straightforward
printf-style positional specifiers. Here’s a basic example of what these are:

NSLog(@"%2$@ %1$@", @"World", @"Hello"); //logs "Hello World"

The “2$” and “1$” in the format specifier simply mean “use the second substitution value” and “use the first substitution value” (respectively). Easy.
Using a special syntax for certain format specifiers (more on this later)

Now that we understand this, we can get on with localizing our NSPredicateEditor. We understand that we need NSLocalizedString() and that we can reposition substituted values using positional specifiers. Now let’s talk about the special format specifier syntax, in the context of another example.

For simplicity, let’s say we have an NSPredicateEditor with three row templates:

A compound row template ([Any, All, None] of the following are true)
A string row template (property [is, is not, contains, begins with, ends with, like, matches] a user-entered-string)
A selection row template (birthMonth is [January - December])

To properly localize these row templates, we simply need to produce some comments:

/**

NSLocalizedStringFromTable(@"%[Any, All, None]@ of the following are true", @"Predicate", @"localize the compound row template")
NSLocalizedStringFromTable(@"%[property]@ %[is, is not, contains, begins with, ends with, like, matches]@ %@", @"Predicate", @"localize the string row template")
NSLocalizedStringFromTable(@"%[birthMonth]@ %[is, is not]@ %[January, February, March, April, May, June, July, August, September, October, November, December]@", @"Predicate", @"localize the selection row template")

**/

Some explanation about what’s going on here:

Why are these in a comment?
Because we don’t actually need this in the compiled code. We just need it in the source code so that the genstrings utility can find it. We won’t actually be using the NSLocalizedString() macros in our final, compiled version.
What’s with the square brackets?
Because this is Objective-C, and we have to use square brackets everywhere, right? RIGHT???

In reality, the square brackets are what makes the magic happen. Each percent modifier (%@) represents a single view on the row template UI. Plain text (ex: “of the following are true”) is also represented as a view (specifically, an NSTextField).

For fields in a row template where you have multiple options, those options are comma-delimited within the square brackets. In the case of the compound row template, there are two fields: a popup that allows you to choose the kind of compound predicate (AND, OR, or NOT), and a field with some clarification text (“of the following are true”). The options for the template must match exactly (case, order, etc) as what you would see in the UI if you were to run your NSPredicateEditor without localization. If you mistype something, or mis-capitalize something else, that translation will not work.

Notice also that some fields don’t have anything to translate. The second row template shows “property”, some various string operators, and then %@. The %@ indicates that this will be replaced with something that cannot be translated. In this case, it would be an NSTextField, since we’re expecting the user to use this to enter some text.

When we run this code through the genstrings utility, we will get a file created (“Predicate.strings”) that contains this:

/* localize the compound row template */
"%[Any]@ of the following are true" = "%[Any]@ of the following are true";
"%[All]@ of the following are true" = "%[All]@ of the following are true";
"%[None]@ of the following are true" = "%[None]@ of the following are true";

/* localize the selection row template */
"%[birthMonth]@ %[is]@ %[January]@" = "%1$[birthMonth]@ %2$[is]@ %3$[January]@";
"%[birthMonth]@ %[is]@ %[February]@" = "%1$[birthMonth]@ %2$[is]@ %3$[February]@";
"%[birthMonth]@ %[is]@ %[March]@" = "%1$[birthMonth]@ %2$[is]@ %3$[March]@";
"%[birthMonth]@ %[is]@ %[April]@" = "%1$[birthMonth]@ %2$[is]@ %3$[April]@";
"%[birthMonth]@ %[is]@ %[May]@" = "%1$[birthMonth]@ %2$[is]@ %3$[May]@";
"%[birthMonth]@ %[is]@ %[June]@" = "%1$[birthMonth]@ %2$[is]@ %3$[June]@";
"%[birthMonth]@ %[is]@ %[July]@" = "%1$[birthMonth]@ %2$[is]@ %3$[July]@";
"%[birthMonth]@ %[is]@ %[August]@" = "%1$[birthMonth]@ %2$[is]@ %3$[August]@";
"%[birthMonth]@ %[is]@ %[September]@" = "%1$[birthMonth]@ %2$[is]@ %3$[September]@";
"%[birthMonth]@ %[is]@ %[October]@" = "%1$[birthMonth]@ %2$[is]@ %3$[October]@";
"%[birthMonth]@ %[is]@ %[November]@" = "%1$[birthMonth]@ %2$[is]@ %3$[November]@";
"%[birthMonth]@ %[is]@ %[December]@" = "%1$[birthMonth]@ %2$[is]@ %3$[December]@";
"%[birthMonth]@ %[is not]@ %[January]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[January]@";
"%[birthMonth]@ %[is not]@ %[February]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[February]@";
"%[birthMonth]@ %[is not]@ %[March]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[March]@";
"%[birthMonth]@ %[is not]@ %[April]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[April]@";
"%[birthMonth]@ %[is not]@ %[May]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[May]@";
"%[birthMonth]@ %[is not]@ %[June]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[June]@";
"%[birthMonth]@ %[is not]@ %[July]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[July]@";
"%[birthMonth]@ %[is not]@ %[August]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[August]@";
"%[birthMonth]@ %[is not]@ %[September]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[September]@";
"%[birthMonth]@ %[is not]@ %[October]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[October]@";
"%[birthMonth]@ %[is not]@ %[November]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[November]@";
"%[birthMonth]@ %[is not]@ %[December]@" = "%1$[birthMonth]@ %2$[is not]@ %3$[December]@";

/* localize the string row template */
"%[property]@ %[is]@ %@" = "%1$[property]@ %2$[is]@ %3$@";
"%[property]@ %[is not]@ %@" = "%1$[property]@ %2$[is not]@ %3$@";
"%[property]@ %[contains]@ %@" = "%1$[property]@ %2$[contains]@ %3$@";
"%[property]@ %[begins with]@ %@" = "%1$[property]@ %2$[begins with]@ %3$@";
"%[property]@ %[ends with]@ %@" = "%1$[property]@ %2$[ends with]@ %3$@";
"%[property]@ %[like]@ %@" = "%1$[property]@ %2$[like]@ %3$@";
"%[property]@ %[matches]@ %@" = "%1$[property]@ %2$[matches]@ %3$@";

Man, that’s a lot of stuff to localize! If you look closely, you can see that every occurrence of NSLocalizedString has been expanded for all possible combinations. So if you have a row template that supports 3 different left expressions, 6 different operators, and 7 different right expressions, then you have to translate 126 different things (3 * 6 * 7 = 126).

One thing that genstrings has conveniently done for us is insert positional specifiers! This allows us to rearrange the order of the string in a translated version, but still get the appropriate value substituted in.

Now that we have this .strings file, we can translate it just like any other strings file, and we can also rearrange fields as necessary:

"%[Any]@ of the following are true" = "%[Cualquiera]@ de las siguientes son verdaderas";
"%[All]@ of the following are true" = "%[Todas]@ de las siguientes son verdaderas";
"%[None]@ of the following are true" = "%[Ningún]@ de las siguientes son verdaderas";

...

"%[property]@ %[is]@ %@" = "%1$[propiedad]@ y %3$@ %2$[son iguales]@"; //literally "property and [value] are equal"
"%[property]@ %[is not]@ %@" = "%1$[propiedad]@ y %3$@ %2$[no son iguales]@";
"%[property]@ %[contains]@ %@" = "%1$[propiedad]@ %2$[contiene]@ %3$@";

...

The final step (beyond including the translated strings files as resources in your application) is that you need to tell your NSPredicateEditor where to find this information. There are two ways to do this:

-[NSPredicateEditor setFormattingStringsFilename:]
-[NSPredicateEditor setFormattingDictionary:]

The first option is usually the way to go. You simply give it the name of your .strings file sans extension (in this case, @"Predicate") and you’re good to go. If it comes across a syntax error, it’ll log it so you can debug it. The problem with this approach is that it only looks inside [NSBundle mainBundle] for the resource. So if you’re writing a plugin (such as a system preference pane), this won’t work.

Fortunately, there’s the second option, and it works like this:

NSString * stringsFile = [[NSBundle bundleForClass:[self class]] pathForResource:@"Predicate" ofType:@"strings"];
NSString * strings = [NSString stringWithContentsOfFile:stringsFile encoding:NSUTF16StringEncoding error:nil];
NSDictionary * formattingDictionary = [strings propertyListFromStringsFileFormat];
[predicateEditor setFormattingDictionary:formattingDictionary];

This is pretty straightforward: load the strings file into memory, use a built-in method to convert it to an NSDictionary, and then give that dictionary to the predicate editor.

So there you have it! An actual explanation on how to localize an NSPredicateEditor! Hopefully anyone who comes across this will find it useful, since it was a total pain to figure out. :)

Enjoy!

Method Swizzling

Sat, 23 Oct 2010 14:15:59 -0700

Recently I wrote about how to dynamically subclass objects in Objective-C, and when that might be useful.

While dynamic subclassing can be really useful, there is one major gotcha that can make it not very effective, and that was hinted at the end of my post: Key-Value Observing.

When you add an observer to an object, the KVO mechanism will dynamically subclass that object to implement the observation logic. For example, consider the following class:

@interface DataObject : NSObject

@property NSInteger dataValue;

@end

When you observe an instance of DataObject<, a dynamic subclass is created. This class is called NSKVONotifying_DataObject, but even that is hidden from you. The KVO subclass is devious; it hides its existence. Consider this:

DataObject * dataObject = [[DataObject alloc] init];

[dataObject addObserver:self forKeyPath:@"dataValue" options:0 context:NULL];

NSLog(@"%@", [dataObject class]);  //logs "DataObject"
NSLog(@"%@", object_getClass(dataObject));  //logs "NSKVONotifying_DataObject"

In other words, the class of an observed object does everything it can to look and behave exactly like the original class. For the most part, this is appropriate behavior. However, when you want to implement your own dynamic subclassing mechanism, it can wreak havoc. A dynamic KVO subclass does not like to be subclassed, because when you remove all the observers from the object, the class of the object is changed back to its original class. This means that even if you manage to dynamically subclass a KVO class, those changes will be lost when the class of the object is changed back to its original class.

So in the case of CHLayoutManager, a different mechanism for automatic cleanup was needed, since it is not uncommon to observe a UI element in order to react to state changes.

After some experimentation, I came up with an alternative: replace the -dealloc method of NSView with a new version.

Now, I don’t have the source to AppKit. I don’t know what NSView is doing under the hood. Fortunately, with Objective-C, that’s not really a problem, because there’s this really neat function in the runtime called method_exchangeImplementations, and it works like this:

+ (void) initialize {
  if (self == [CHLayoutManager class]) {
    Class nsview = [NSView class];

    SEL dynamicDealloc = @selector(chlayoutautoremove_dynamicDealloc);

    Method newDealloc = class_getInstanceMethod(self, dynamicDealloc);
    if (newDealloc != NULL) {
      class_addMethod(nsview, dynamicDealloc, method_getImplementation(newDealloc), method_getTypeEncoding(newDealloc));
      newDealloc = class_getInstanceMethod(nsview, dynamicDealloc);

      if (newDealloc != NULL) {
        Method originalDealloc = class_getInstanceMethod(nsview, @selector(dealloc));
        method_exchangeImplementations(originalDealloc, newDealloc);
      }
    }
  }
}

- (void) chlayoutautoremove_dynamicDealloc {
  if ([self isKindOfClass:[NSView class]]) { //to prevent people from being stupid
    [[CHLayoutManager sharedLayoutManager] removeConstraintsFromView:(NSView *)self];
    [[CHLayoutManager sharedLayoutManager] setLayoutName:nil forView:(NSView *)self];
    //THIS IS NOT A RECURSIVE CALL
    [self chlayoutautoremove_dynamicDealloc];
  }
}

This is a two step process:

First, we find the NSView class and add a new method to it. This method, called -chlayoutautoremove_dynamicDealloc simply performs cleanup with the layout manager singleton. After we add the method to NSView, we swap the implementations of -dealloc and -chlayoutautoremove_dynamicDealloc. This means that -[NSView dealloc] will invoke the implementation of -chlayoutautoremove_dynamicDealloc, and -[NSView chlayoutautoremove_dynamicDealloc] will invoke the original -dealloc code. Essentially, this is more or less injecting code into NSView that will be executed right before the -dealloc code gets executed.

Neat!

Fun with Objective-C

Getting the IMP of the current method

Pretty Pretty

Dumbfounded

Parsing Mathematical Expressions

The Guts

Tokenization

Grouping

Resolving

Implicit Multiplication

Analysis

Subclassing NSInputStream

How to learn Cocoa

Be Curious

Don’t Be Satisfied

Final Thoughts

How I do my singletons

Why do Strings in Objective-C have to be preceded with an @?

Since this is an Obj-c blog,I have a question for you why would they make another C with OOP,what's wrong with C++?

I've really been enjoying your posts, but you don't have any personal information on your site, as far as I could find. Who are you?

Using custom functions with NSExpression

The Syntax

Custom Functions

Venturing Toward the Absurd

A Caution

Wrap Up

What the heck is SUBQUERY?

The Syntax

The Collection

The Variable

The Predicate

TL;DR

So what?

Rule of thumb

Example

Creating an advanced NSPredicateEditorRowTemplate

The Setup

The Problems

The Solutions

Solving the operator problem

Solving the relative date problem

The Row Template

The Interface

The Implementation

Wrap-up

Mathematically evaluating NSStrings

Creating a simple NSPredicateEditorRowTemplate

What’s going on under the hood

The UI

Building a custom row template

The Interface

The Implementation

Using this template

Localizing this template

Wrap-Up

Abusing NSPredicate

NSPredicate Parsing

NSExpression Solving

Defining custom key path operators

Mike Ash: Creating Classes at Runtime

Followup to Localizing NSPredicateEditor

Localizing NSPredicateEditor

Method Swizzling

Since this is an Obj-c blog,I have a question for you

why would they make another C with OOP,what's wrong with C++?