Permalink
Fetching contributors…
Cannot retrieve contributors at this time
129 lines (115 sloc) 5.48 KB
//
// MTLModel+NSCoding.h
// Mantle
//
// Created by Justin Spahr-Summers on 2013-02-12.
// Copyright (c) 2013 GitHub. All rights reserved.
//
#import "MTLModel.h"
/// Defines how a MTLModel property key should be encoded into an archive.
///
/// MTLModelEncodingBehaviorExcluded - The property should never be encoded.
/// MTLModelEncodingBehaviorUnconditional - The property should always be
/// encoded.
/// MTLModelEncodingBehaviorConditional - The object should be encoded only
/// if unconditionally encoded elsewhere.
/// This should only be used for object
/// properties.
typedef enum : NSUInteger {
MTLModelEncodingBehaviorExcluded = 0,
MTLModelEncodingBehaviorUnconditional,
MTLModelEncodingBehaviorConditional,
} MTLModelEncodingBehavior;
/// Implements default archiving and unarchiving behaviors for MTLModel.
@interface MTLModel (NSCoding) <NSCoding>
/// Initializes the receiver from an archive.
///
/// This will decode the original +modelVersion of the archived object, then
/// invoke -decodeValueForKey:withCoder:modelVersion: for each of the receiver's
/// +propertyKeys.
///
/// Returns an initialized model object, or nil if a decoding error occurred.
- (id)initWithCoder:(NSCoder *)coder;
/// Archives the receiver using the given coder.
///
/// This will encode the receiver's +modelVersion, then the receiver's properties
/// according to the behaviors specified in +encodingBehaviorsByPropertyKey.
- (void)encodeWithCoder:(NSCoder *)coder;
/// Determines how the +propertyKeys of the class are encoded into an archive.
/// The values of this dictionary should be boxed MTLModelEncodingBehavior
/// values.
///
/// Any keys not present in the dictionary will be excluded from the archive.
///
/// Subclasses overriding this method should combine their values with those of
/// `super`.
///
/// Returns a dictionary mapping the receiver's +propertyKeys to default encoding
/// behaviors. If a property is an object with `weak` semantics, the default
/// behavior is MTLModelEncodingBehaviorConditional; otherwise, the default is
/// MTLModelEncodingBehaviorUnconditional.
+ (NSDictionary *)encodingBehaviorsByPropertyKey;
/// Determines the classes that are allowed to be decoded for each of the
/// receiver's properties when using <NSSecureCoding>. The values of this
/// dictionary should be NSArrays of Class objects.
///
/// If any encodable keys (as determined by +encodingBehaviorsByPropertyKey) are
/// not present in the dictionary, an exception will be thrown during secure
/// encoding or decoding.
///
/// Subclasses overriding this method should combine their values with those of
/// `super`.
///
/// Returns a dictionary mapping the receiver's encodable keys (as determined by
/// +encodingBehaviorsByPropertyKey) to default allowed classes, based on the
/// type that each property is declared as. If type of an encodable property
/// cannot be determined (e.g., it is declared as `id`), it will be omitted from
/// the dictionary, and subclasses must provide a valid value to prevent an
/// exception being thrown during encoding/decoding.
+ (NSDictionary *)allowedSecureCodingClassesByPropertyKey;
/// Decodes the value of the given property key from an archive.
///
/// By default, this method looks for a `-decode<Key>WithCoder:modelVersion:`
/// method on the receiver, and invokes it if found.
///
/// If the custom method is not implemented and `coder` does not require secure
/// coding, `-[NSCoder decodeObjectForKey:]` will be invoked with the given
/// `key`.
///
/// If the custom method is not implemented and `coder` requires secure coding,
/// `-[NSCoder decodeObjectOfClasses:forKey:]` will be invoked with the
/// information from +allowedSecureCodingClassesByPropertyKey and the given `key`. The
/// receiver must conform to <NSSecureCoding> for this to work correctly.
///
/// key - The property key to decode the value for. This argument cannot
/// be nil.
/// coder - The NSCoder representing the archive being decoded. This
/// argument cannot be nil.
/// modelVersion - The version of the original model object that was encoded.
///
/// Returns the decoded and boxed value, or nil if the key was not present.
- (id)decodeValueForKey:(NSString *)key withCoder:(NSCoder *)coder modelVersion:(NSUInteger)modelVersion;
/// The version of this MTLModel subclass.
///
/// This version number is saved in archives so that later model changes can be
/// made backwards-compatible with old versions.
///
/// Subclasses should override this method to return a higher version number
/// whenever a breaking change is made to the model.
///
/// Returns 0.
+ (NSUInteger)modelVersion;
@end
/// This method must be overridden to support archives created by older versions
/// of Mantle (before the `MTLModel+NSCoding` interface existed).
@interface MTLModel (OldArchiveSupport)
/// Converts an archived external representation to a dictionary suitable for
/// passing to -initWithDictionary:.
///
/// externalRepresentation - The decoded external representation of the receiver.
/// fromVersion - The model version at the time the external
/// representation was encoded.
///
/// Returns nil by default, indicating that conversion failed.
+ (NSDictionary *)dictionaryValueFromArchivedExternalRepresentation:(NSDictionary *)externalRepresentation version:(NSUInteger)fromVersion;
@end