nosewheelie

Technology, mountain biking, politics & music.

Simplifying JSON Parsing Using FunctionalKit

without comments

Introduction

At MoGeneration we write a lot of iPhone clients that integrate with back end web services. Thankfully, most of these expose their data as JSON, which is quite easy to parse into a corresponding NSDictionary using json-framework. However, dealing with errors, non-existant values & then turning the parsed NSDictionary into domain model instances can be tricky. It often involves writing a lot of repetitive code and manual error handling. We can however do a lot better.

This post will show you the basics of improving the way JSON is parsed by using some simple techniques from FunctionalKit. There’s lots of in depth explanation going on here, look towards the code samples if you want a quick summary.

JSON

So to begin with, here’s the JSON. It comes from a current project for the guys over at Perkler. This is the result of looking up the current user’s likes (stuff they’re interested in knowing about):

{
  "meta":{
    "action":"getLikes",
    "output":"json",
    "search":false,
    "location": {
      "geo_id":"1999",
      "geo_location":"Victoria, Australia",
      "geo_latitude":"-36.558800",
      "geo_longitude":"145.468994",
      "geo_altitude":"0.000000",
      "geo_country_code":"AU",
      "geo_administrative_area":"Victoria",
      "geo_locality":"",
      "geo_thoroughfare":"",
      "geo_postalcode":"",
      "geo_accuracy":"2",
      "score":"0"
    }
  },
  "likes":["bikes","coffee","girls","haskell"]
}

For this post, we’ll ignore the metadata, we’re mainly concerned with the likes array.

Ground Rules

Let’s begin by setting up some ground rules, there’s a bunch of error conditions we need to handle:

  • We don’t know if the results are valid JSON, our parser returns nil on error;
  • The likes array may not be there;
  • The likes array may be nil;
  • The likes array may be empty;

There are other issues such as the underlying HTTP transport failing, but we’re a little further along the chain here, so we’re not worrying about that (though, these techniques work just as well there).

Baseline

Back in the bad old days we’d do a bunch of nil checks, and only proceed if things weren’t nil. We also return nil because people in Objective-C like that sort of thing.

Here’s the top level code that takes a string, parses it and invokes our parser to turn it into an array of PLLikes.

- (NSArray *)getLikes:(NSString *)jsonEncodedResults {
    NSDictionary *jsonDecodedResults = [jsonEncodedResults JSONValue];
    NSArray *likes = [likesParser parseGetLikesResults:jsonDecodedResults];
}

And here’s our parser implementation, with its myriad of nil checks, we’re letting it do all the checking (including handling the nil from the parser’s JSONValue).

@implementation GetLikesParser
 
- (NSArray *)parseGetLikesResults:(NSDictionary *)results {
    if (results == nil) {
        return nil;
    } else {
        NSArray *likes = [results objectForKey:@"likes"];
        if (likes == nil) {
          return nil;
        } else {
            NSMutableArray *convertedlikes = 
                  [NSMutableArray arrayWithCapacity:[likes count]];
            for (NSString *like in likes) {
                [convertedlikes addObject:[PLLike value:like]];
            }
            return convertedlikes;
        }
    }
}
 
@end

Isn’t that nice!

Introducing Option

We’ve established our baseline, now what’s wrong with this & how can we make it better?

To start with, we have a bunch of nil checks and the code doing the work is buried under a bunch of layers, obscuring what it actually does. Let’s start to make it better by introducing Option. Option is a way of denoting that we either have a value, or, we don’t, in other words an optional value. If we have a value we say we have a Some with the value in it, and if we have nothing, we have a None. Simple hey? These are represented in FunctionalKit using FKOption.

Let’s rewrite the above example to use Option, to make it easy to follow, we’ll do a direct translation.

@implementation GetLikesParser
 
- (FKOption *)parseGetLikesResults:(NSDictionary *)results {
    FKOption *maybeResults = [FKOption fromNil:results];
    if (maybeResults.isNone) {
        return [FKOption none];
    } else {
        FKOption *maybeLikes = [FKOption fromNil:[maybeResults.some objectForKey:@"likes"]];
        if (maybeLikes.isNone) {
            return [FKOption none];
        } else {
            NSMutableArray *convertedlikes = 
                  [NSMutableArray arrayWithCapacity:[maybeLikes.some count]];
            for (NSString *like in maybeLikes.some) {
                [convertedlikes addObject:[PLLike value:like]];
            }
            return [FKOption some:convertedlikes];
        }
    }
}
 
@end

Let’s have some commentary on the above example.

To create an option from a potentially nil value, we use the constructor fromNil:. If the value is nil we’ll get None otherwise we’ll get a Some containing the value.

We prefix the variable name with “maybe”, this is not required, it’s just something that I like to do as it denotes that it “may be” the thing we want, or it may not be.

To pull the value out of an optional value, we call the some property (or message it if you like). To construct a Some with a value we know is non-nil, we call the some: constructor.

We’re also returning an optional value, so the code in our top level method needs to handle this also, we’ve not shown that here. Notice also that as Objective-C doesn’t support parametric polymorphism, we’ve lost some degree of compiler safety, we no longer know at compile time what FKOption holds, it’s really an FKOption[NSArray[PLLike]], but we can’t enforce that.

But is this really any better? As we’ve done a literal translation, we still have a bunch of checks that really aren’t much better than what we had. They’re nil checks in a different form.

Don’t fret, we can do better.

Staying inside the Option

What all these nil check equivalents (option.isNone) are really doing is just making sure we only continue executing while we have a non-nil value, or a Some in this case. What we want is: If we have a None, return that, however if we have a Some do something with the value in that Some. We can apply this rule at each level of our checking.

At this point, we’ll also pull the function out that does the work. This will make it simpler to figure out the actual core of our problem (that our checks were obscuring) as well as giving us a nice hook to create a function from.

Let’s have a crack at that code.

@implementation GetLikesParser
 
- (FKOption *)parseGetLikesResults:(NSDictionary *)results {
    FKOption *maybeResults = [FKOption fromNil:results];
    FKOption *maybeLikes = [maybeResults bind:functionTS(self, pullOutLikes:)];
    return [maybeLikes map:functionTS(self, parseLikes:)];
}
 
- (FKOption *)pullOutLikes:(NSDictionary *)results {
    return [FKOption fromNil:[results objectForKey:@"likes"]];
}
 
- (NSArray *)parseLikes:(NSArray *)likes {
    NSMutableArray *convertedlikes = [NSMutableArray arrayWithCapacity:[maybeLikes.some count]];
    for (NSString *like in maybeLikes.some) {
        [convertedlikes addObject:[PLLike value:like]];
    }
    return convertedlikes;
}
 
@end

How it all works

Before we discuss what this code actually does, let’s have a look at it more closely. Nowhere have we actually explicitly pulled the value out of the Option. We’ve left it inside the Option; it takes care of safely unpacking the value (if it’s there) and providing it to our functions!

So what is this magic map: function doing? If you’ve used Ruby or a functional language, you’ve probably used this before. Cocoa has a similar concept in NSArray‘s -(void)makeObjectsPerformSelector:(SEL)aSelector. The important thing to note is that Option is a container class for other values, just like an array is. In fact, you can think of Option as an array that will either contain zero or one element, but no more.

Mapping across a container class is the same as iterating over it using a conventional for loop, with the benefit that the container class takes care of the iteration, as calling code we’re never exposed to it.

Here’s how map: works. For each time around the loop, the element at that point (at that index if you like) is pulled out of the container and provided to a function. The function transforms the element from its current value into another one. Take as an example an array of numbers. We could map over this array turning each number into a string. The result of mapping across this array of numbers is an array of strings. Notice also that because we’re just iterating over the container, if the container is empty we don’t start the iteration so never invoke the function (this is important!).

To abstract this a little, you start with a container of some type, and end up with a container of another type. An important concept to note is that the container type never changes; start with an array, end up with an array.

If you’re up for a little bit more of an interlude, the function that map: takes looks has types as follows: f :: a ➝ b. This means that it will take something of type a and return something of type b, where a and b can be any types at runtime, for example a function that converts a number to a string. So using our abstraction from above, if we had a container of type C (say an NSArray) that contained as (say NSNumbers) and a function that turned as to bs (NSNumbers to NSStrings) then we can get a C containing bs. Looking at the types again, map: looks like this: map :: C a ➝ (a ➝ b) ➝ C b. Phew…

Let’s get back to our Option again.

If we consider Option to be a container class (which it is) similar to an array, then if we map over an empty Option – a None – then all we get back is an empty Option – a None. However if we map over a non-empty Option – a Some – then we get back a non-empty Option – a Some. This is the magic behind how our code can deal with the presence or absence of nils; if we have nothing, the functions never get called, and we get back another (empty) Option.

This style of mapping can be chained together for as many options as we like, if we don’t have anything nothing happens, if we do, we process it and keep going. If at any point in the chain we have a nil the chain effectively stops processing. However we only write one set of code to do this, so we’re basically pretending that errors don’t happen, but if they do, they’re handled effectively.

You will also have noticed the other magic function we’re using, bind:. I’ve not talked about it in detail as it is very similar to map:. The only difference being that whereas map: takes a function from a ➝ b, bind: takes a function from a ➝ C b and produces a flattened C b, that is: bind :: C a ➝ (a ➝ C b) ➝ C b. This allows us to safely handle a potential nil coming out of an NSDictionary (for the @"likes" key) and still chain together our processing.

Back to the code

So now we've had that nice little chat, what is the code doing?

We have three basic blocks of work going on: 1) mapping over options 2) pulling out likes from an NSDictionary and 3) turning string likes into PLLikes. We've pulled these last two blocks of work out into methods by themselves. We might normally do this to clean up the code when refactoring, but in this case it allows us call the methods as the functions passed to a map:. Remember the interlude above?

FunctionalKit provides a number of ways to create functions. functionTS is a macro that constructs a new FKFunction from a target object and a selector (there's long hand non-macro ways to do this also). Sending a selector to a target object is fairly routine in Objective-C, all FKFunction does is wrap the target and selector up into a convenient package and allow us to pass it into map:. Once Objective-C gets closures the need to pull out these methods will be removed, eliminating the need to use these macros in maps, binds, etc.

Simplifying

Now that we know what mapping is, that last function is crying out to be a map! Let's see this in action.

@implementation GetLikesParser
 
- (FKOption *)parseGetLikesResults:(NSDictionary *)results {
    FKOption *maybeResults = [FKOption fromNil:results];
    FKOption *maybeLikes = [maybeResults bind:functionTS(self, pullOutLikes:)];
    return [maybeLikes map:functionTS(self, parseLikes:)];
}
 
- (FKOption *)pullOutLikes:(NSDictionary *)results {
    return [FKOption fromNil:[results objectForKey:@"likes"]];
}
 
- (NSArray *)parseLikes:(NSArray *)likes {
    return [likes map:functionTS(self, parseLike:)];
}
 
- (PLLike *)parseLike:(NSString *)like {
    return [PLLike value:like];
}
 
@end

Woah... that's lots of little functions doing not much (wouldn't you love a closure?). Luckily we can go even further as we can use the function macros on class methods, allowing us to remove that last function.

@implementation GetLikesParser
 
- (FKOption *)parseGetLikesResults:(NSDictionary *)results {
    FKOption *maybeResults = [FKOption fromNil:results];
    FKOption *maybeLikes = [maybeResults bind:functionTS(self, pullOutLikes:)];
    return [maybeLikes map:functionTS(self, parseLikes:)];
}
 
- (FKOption *)pullOutLikes:(NSDictionary *)results {
    return [FKOption fromNil:[results objectForKey:@"likes"]];
}
 
- (NSArray *)parseLikes:(NSArray *)likes {
    return [likes map:functionTS([PLLike classAsId], value:)];
}
 
@end

Looking better, but there's another function we can remove; all pullOutLikes: does is provide a nil-safe accessor our dictionary. FunctionalKit provides a nil-safe extension on NSDictionary: -(FKOption*)maybeObjectForKey:(id)key. Let's try that shall we.

@implementation GetLikesParser
 
- (FKOption *)parseGetLikesResults:(NSDictionary *)results {
    FKOption *maybeResults = [FKOption fromNil:results];
    FKOption *maybeLikes = [maybeResults bind:functionTS(self, pullOutLikes:)];
    return [maybeLikes map:functionTS(self, parseLikes:)];
}
 
- (FKOption *)pullOutLikes:(NSDictionary *)results {
    return [results maybeObjectForKey:@"likes"];
}
 
- (NSArray *)parseLikes:(NSArray *)likes {
    return [likes map:functionTS([PLLike classAsId], value:)];
}
 
@end

OK, that's a little nicer, but we've still got a function that does not much at all. Let's try another macro: functionSA, it creates a function from a selector and its argument. In our example we can pass it directly to our option's bind: method.

@implementation GetLikesParser
 
- (FKOption *)parseGetLikesResults:(NSDictionary *)results {
    FKOption *maybeResults = [FKOption fromNil:results];
    FKOption *maybeLikes = [maybeResults bind:functionSA(maybeObjectForKey:, @"likes")];
    return [maybeLikes map:functionTS(self, parseLikes:)];
}
 
- (NSArray *)parseLikes:(NSArray *)likes {
    return [likes map:functionTS([PLLike classAsId], value:)];
}
 
@end

All right, we're getting close.

Some heavy lifting

So our code is now nil-safe, but it still a little verbose for our liking. Can we remove any more of these little functions we've created? Turns out we can.

We have a function already to turn an NSString representation of a like into a PLLike representation; functionTS([PLLike classAsId], value:). We see it in use when mapping over our array of likes. Wouldn't it be nice to have a way to turn that function on an individual like into a function on an array of likes? Thankfully such a thing exists. The process of taking a function on a single element of a container class and being able to apply it to the container class itself is called lifting a function.

Let's rewrite the example using a lift to turn our parsing function on a single like into a parsing function on an array of likes.

@implementation GetLikesParser
 
- (FKOption *)parseGetLikesResults:(NSDictionary *)results {
    FKOption *maybeResults = [FKOption fromNil:results];
    FKOption *maybeLikes = [maybeResults bind:functionSA(maybeObjectForKey:, @"likes")];
    return [maybeLikes map:[NSArray liftFunction:functionTS([PLLike classAsId], value:)]];
}
 
@end

We've now been able to remove yet another little function clouding up our code. Objective-C noise not withstanding, our code is closer to the core of what we're trying to achieve: if we have results pull the likes out; if we have likes, turn each one into a PLLike.

Let's go one step further and inline the maybeLikes variable.

@implementation GetLikesParser
 
- (FKOption *)parseGetLikesResults:(NSDictionary *)results {
    FKOption *maybeLikes = [[FKOption fromNil:results] bind:functionSA(maybeObjectForKey:, @"likes")];
    return [maybeLikes map:[NSArray liftFunction:functionTS([PLLike classAsId], value:)]];
}
 
@end

Compare this completed version to the one we started with, it's one hell of a lot nicer isn't it? Which one would you prefer?

Conclusion

The process that we've followed may seem a little convoluted and foreign, but we've really just applied simple rules at each step of the way. Once you get used to functional techniques these patterns become easier to spot and their application easier to handle. Granted, understanding this kind of code does take some time, but the benefits of doing so are massive, as we've seen, code literally melts away, becomes clearer and more bug-free.

Another major benefit is each of these little chunks of logic can be viewed in complete isolation from each other, allowing you to easily reason about the behaviour of each one, and then as well as the whole. The code is now also closer to the actual semantics of what we're trying to achieve; we have no for loop boiler plate clouding what we're trying to achieve.

If you're developing iPhone apps or even for Mac OS X give FunctionalKit a go and get in touch if you're interested in contributing.

Written by Tom Adams

April 1st, 2009 at 2:18 pm

Leave a Reply