AutoCoding is a category on NSObject that provides automatic support for NSCoding to any object. This means that rather than having to implement the
encodeWithCoder methods yourself, all the model classes in your app can be saved or loaded from a file without you needing to write any additional code.
Of course no automated system can read your mind, so AutoCoding does place certain restrictions on how you design your classes; For example, you should avoid using structs that are not already NSCoding compliant via NSValue.
However, use of AutoCoding is by no means and all-or-nothing decision. You are free to implement your own NSCoding methods on any class in your project and they will simply override the automatically generated methods.
AutoCoding 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.
- Supported build target - iOS 5.0 / Mac OS 10.7 (Xcode 4.2, Apple LLVM compiler 3.0)
- Earliest supported deployment target - iOS 4.3 / Mac OS 10.6
- Earliest compatible deployment target - iOS 3.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 iOS 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.
AutoCoding is compatible with both ARC and non-ARC compile targets.
AutoCoding is fully thread-safe.
To use the AutoCoding category in your project, just drag the NSObject+AutoCoding files into your project.
The NSObject(AutoCoding) category extends NSObject with the following methods. Since this is a category, every single Cocoa object, including AppKit/UIKit objects and BaseModel instances inherit these methods.
- (NSArray *)codableKeys;
This method returns an array containing the names of all the properties of the object that will be automatically saved and loaded when the object is archived using NSKeyedArchiver/Unarchiver. This array is automatically generated by scanning the properties defined in the class definition at runtime. It is not normally necessary to override this method; If you wish to exclude certain properties from the serialisation process, you can return them in the
uncodableKeys method and they will be automatically removed from this array.
- (NSArray *)uncodableKeys;
This method can be used to exclude certain properties from automatic coding without having to override the
codableKeys method or implement the
encodeWithCoder: methods yourself from scratch. The default return value of this method is nil. Implement the method and return an array containing the names of any properties you wish to exclude.
+ (id)objectWithContentsOfFile:(NSString *)path;
This attempts to load the file using the following sequence: 1) If the file is an NSCoded archive, load the root object and return it, 2) If the file is an ordinary Plist, load and return the root object, 3) Return the raw data as an NSData object. If the de-serialised object is not a subclass of the class being used to load it, an exception will be thrown (to avoid this, call the method on
NSObject instead of a specific subclass).
- (void)writeToFile:(NSString *)filePath atomically:(BOOL)useAuxiliaryFile;
This attempts to write the file to disk. This method is overridden by the equivalent methods for NSData, NSDictionary and NSArray, which save the file as a human-readable XML Plist rather than an binary NSCoded Plist archive, but the
objectWithContentsOfFile: method will correctly de-serialise these again. For any other object it will serialise the object using the NSCoding protocol and write out the file as a NSCoded binary Plist archive.
If you want to perform initialisation of the class prior to the properties being loaded via NSCoding, you can use the
initmethod, which is called before the decoding occurs.
If you want to perform some cleanup or post-processing after the object has been loaded via NSCoding, you can use the
awakeAfterUsingCoder:method, which is defined in the NSObject class reference.
You can add additional coding/decoding logic by overriding the
encodeWithCoder:methods. As long as you call the [super ...] implementation, the auto-coding will still function. If you are using the BaseModel superclass, you should override the
setWithCoder:method instead of
If you wish to substitute a different class for properties of a given type - for example if you have changed the name of a class but wish to retain compatibility with files saved using the old class name, you can substitute a different class for a given name by using the