HRCoder is a replacement for the NSKeyedArchiver and NSKeyedUnarchiver classes. Although the NSKeyedArchiver writes data in binary Plist format, the structure of the Plist makes it hard to read, and nearly impossible to generate by hand.
The HR stands for Human Readable. HRCoder saves files in a simpler format than NSKeyedArchiver; Standard objects such as strings, dictionaries, arrays, numbers, booleans and binary data are all saved and loaded using the standard plist primitives, and any other type of object is saved as a simple dictionary, with the addition of a $class key to indicate the object type.
This makes it possible to easily generate HRCoder-compatible Plist files by hand, and then load them using the standard NSCoding protocol. You can also read and manually edit files saved by the HRCoder class without fear of corrupting the file.
The simple dictionary/array-based format used by HRCoding can also be easily stored as JSON, opening up more options for serialisation (NSKeyedArchiver is tied to Plists and cannot easily be used to save as JSON without creating a Plist as an intermediate step).
HRCoder is designed to work with the AutoCoding library (https://github.com/nicklockwood/AutoCoding), which can automatically write the
encodeWithCoder: methods for your classes. Check out the AutoTodoList example to see how this works.
HRCoder is also designed to work hand-in-hand with the BaseModel library (https://github.com/nicklockwood/BaseModel) to form the basis for building a powerful model hierarchy for your project with minimal effort. Check the HRTodoList example included in the BaseModel repository for an example of how these libraries can work together.
Supported OS & SDK Versions
- Supported build target - iOS 5.1 / Mac OS 10.7 (Xcode 4.3, Apple LLVM compiler 3.1)
- Earliest supported deployment target - iOS 4.3 / Mac OS 10.6
- Earliest compatible deployment target - iOS 4.0 / Mac OS 10.6
NOTE: 'Supported' means that the library has been tested with this version. 'Compatible' means that the library should work on this OS version (i.e. it doesn't rely on any unavailable SDK features) but is no longer being tested for compatibility and may require tweaking or bug fixes to run correctly.
HRCoder is compatible with both ARC and non-ARC compile targets.
HRCoder is fully thread-safe.
To use the HRCoder category in your project, just drag the HRCoder class files into your project.
HRCoder implements the following methods, which mirror those of the NSKeyedArchiver and NSKeyedUnarchiver classes.
+ (id)unarchiveObjectWithPlist:(id)plist; - (id)unarchiveObjectWithPlist:(id)plist;
Constructs an object tree from an encoded plist and returns it. The plist parameter can be any object that is natively supported by the Plist format. This would typically be a container object such as an NSDictionary or NSArray. If any other kind of object is supplied it will be returned without modification.
Note that this object need not actually be loaded from a Plist - you can create such an object quite easily using JSON or another compatible serialisation format.
+ (id)unarchiveObjectWithFile:(NSString *)path; - (id)unarchiveObjectWithFile:(NSString *)path;
Loads a file in Plist format and returns an unarchived object tree by calling
unarchiveObjectWithPlist: on the root object in the file. Supports text, xml or binary-formatted Plist files. Files are loaded using the
NSPropertyListMutableContainersAndLeaves option to ensure that mutability of objects is preserved when serialising. There is a small performance overhead to this, so if you'd prefer immutable objects, load the plist yourself directly using the
+ (id)archivedPlistWithRootObject:(id)object; - (id)archivedPlistWithRootObject:(id)object;
Encodes the passed object as a hierarchy of Plist-compatible objects, and returns it. The resultant object will typically be one of NSDictionary, NSArray, NSString, NSData, NSDate or NSNumber. This object is then safe to pass to NSPropertyListSerialisation for conversion to raw data or saving to a file (either a Plist or JSON, etc).
+ (BOOL)archiveRootObject:(id)rootObject toFile:(NSString *)path; - (BOOL)archiveRootObject:(id)rootObject toFile:(NSString *)path;
Encodes the passed object by calling
archivedPlistWithRootObject: and then saves it as a binary property list at the file path specified. The file is saved atomically to prevent data corruption.
Any ordinary Plist can be loaded using HECoder and it will behave the same way as if you loaded it using
NSPropertyListSerialization. To add custom classes to the Plist, define the object as if it was a dictionary, but add an additional
$class key with the class name of the object. For example, this code will result in an ordinary NSDictionary:
<dict> <key>coming</key> <string>Hello</string> <key>going</key> <string>Goodbye</string> </dict>
But this will load an object of class
Greetings (assuming that class exists in your project).
<dict> <key>$class</key> <string>Greetings</string> <key>coming</key> <string>Hello</string> <key>going</key> <string>Goodbye</string> </dict>
Another feature of NSCoding that isn't supported by ordinary Plists is circular references. HRCoding supports this using the an aliasing mechanism. If you want to re-use an object in another place within your object hierarchy, you can do this using the following syntax:
<dict> <key>$alias</key> <string>path.to.the.object</string> </dict>
The alias value is a key path to the original object within the hierarchy. To see this in context, here is a simple example of how this would work:
<dict> <key>object1</key> <string>Hello World</string> <key>object2</key> <dict> <key>$alias</key> <string>object1</string> </dict> </dict>
Once loaded, the object1 and object2 properties will both point at the same "Hello World" string instance (not just the same value, but the same actual object). This also works with arrays - just use the array index as the alias key:
<array> <string>Hello World</string> <dict> <key>$alias</key> <string>0</string> </dict> </array>
Forward references are permitted in aliases (i.e. aliasing an object which is declared later in the hierarchy), however this should be avoided as possible as it involves inserting
HRCoderAliasPlaceholder objects as the object tree is deserialised, and then replacing these later, which incurs a slight performance penalty.
Note that if you are using aliases you should be careful not to call methods on deserialised objects insider your
initWithCoder: method, as they may not always be of the expected type until loading is complete.