Serialization in Cocoa - Property Lists (corrected to text and source code)

Introduction

In the last serialization article, I showed you how to use the archiving capabilities of Cocoa. Cocoa is very powerful, so here goes yet another way to serialize objects: Property Lists. Property lists do not give you a way to specify how and what data is to be serialized. You are forced to use plist-serializable data types: NSArray, NSDictionary, NSData, NSDate, NSNumber, and NSString, their mutable twins, or their Core Foundation equivalents. So, it’s impossible to serialize an arbitrary object like you would with archives, but it is very convenient to store configuration properties, that are usually stored in dictionaries, etc.

There are several types of property lists: XML, binary, and legacy. Legacy property lists store data in a deprecated format going back to NextSTEP days. That format is currently only supported in read-only mode and we will not talk about it. The default plist format is XML: it generates human readable XML files that can get quite large, but are easy to modify and debug. Lastly, the binary plist format is much smaller and efficient and can be used to pass serialized data between multiple applications. Such format is especially useful for communicating with constrained devices, such as iPhone.

Creating Plists from scratch

• Through NSArray:
        BOOL success = [books writeToFile:@"/Users/vpasman/test1.plist" atomically:NO];
        if (success == NO)
        {
                NSLog(@"failed saving the XML plist file");
        }
• Through serialization API:
        NSString *error;
        NSData *xmlData = [NSPropertyListSerialization dataFromPropertyList:books format:NSPropertyListXMLFormat_v1_0 errorDescription:&error];
        if(xmlData)
        {
                NSLog(@"No error creating XML data.");
                [xmlData writeToFile:@"/Users/vpasman/test1.plist" atomically:YES];
        }
        else
        {
                NSLog(error);
                [error release];
        }
• Through Core Foundation:
        NSData *xmlData = (NSData *)CFPropertyListCreateXMLData(kCFAllocatorDefault, (CFPropertyListRef)books);
        if(xmlData)
        {
                NSLog(@"No error creating XML data.");
                [xmlData writeToFile:@"/Users/vpasman/test1.plist" atomically:YES];
        }
        else
        {
                NSLog(error);
                [error release];
        }

Our options are very similar if we were to save a binary plist, except that we cannot use NSArray’s writeToFile message (it defaults to XML):

• Through serialization API:
        NSString *error;
        NSData *xmlData = [NSPropertyListSerialization dataFromPropertyList:books format:NSPropertyListBinaryFormat_v1_0 errorDescription:&error];
        if(xmlData)
        {
                NSLog(@"No error creating XML data.");
                [xmlData writeToFile:@"/Users/vpasman/test2.plist" atomically:YES];
        }
        else
        {
                NSLog(error);
                [error release];
        }

Loading and Modifying Plists

For the XML few examples, I will be using a plist file (a.k.a. test.plist in code sample) borrowed from the “Property List Programming Guide”.

Loading plists is very similar to saving, just the opposite. Here is how I will read the XML data:

• I just refuted Apple’s claim of how to enforce plist-mutability. According to Apple’s documentation, “NSMutableDictionary *dict = [NSMutableDictionary dictionaryWithContentsOfFile:@"/Users/vpasman/test.plist"];” creates a mutable dictionary and “NSDictionary *dict = [NSDictionary dictionaryWithContentsOfFile:@"/Users/vpasman/test.plist"];” creates an immutable dictionary. Those statements are obviousely wishful thinking. Example above will produce warnings but run, not crash, and generate proper output!

We will load a binary plist in a similar fashion to the XML one:

Workarounds

• Im/Mutability. Despite inconsistencies in Apple’s documentation, there is a way to make a plist immutable in run-time. What this means is that if you were to try to modify an immutable plist in run-time, an exception will be thrown and application will crash. Here is how we will do that:
        // If were to use mutabilityOption:NSPropertyListImmutable,
        // we would get a run time error when trying to insert another volume
        NSPropertyListFormat format;
        books = [NSPropertyListSerialization propertyListFromData:binData
 mutabilityOption:NSPropertyListImmutable format:&format errorDescription:&error];
• If I wanted to create a plist from scratch, the limitation of not being able to store NSNumbers and NSDates may seem severe. Luckily, NSDate and NSNumber instances can be converted to NSString. Thus we’d have to do a bit of extra work, but the constraint does not seem to be very severe.

Conclusion

Property Lists are very useful for passing information between processes, storing configuration parameters, and much more. It’s a very powerful concept that nicely expands Mac and iPhone OS serialization and configuration capabilities.

Sample Code for this article can be found here.

Vlad