Project import
diff --git a/LICENSE.md b/LICENSE.md
new file mode 100644
index 0000000..0c46720
--- /dev/null
+++ b/LICENSE.md
@@ -0,0 +1,21 @@
+**Copyright (c) 2012 - 2014, GitHub, Inc.**
+**All rights reserved.**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+**This project uses portions of code from the Proton framework.**
+**Proton is copyright (c) 2012, Bitswift, Inc.**
+**All rights reserved.**
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+ * Neither the name of the Bitswift, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/Mantle/MTLJSONAdapter.h b/Mantle/MTLJSONAdapter.h
new file mode 100644
index 0000000..368c5ab
--- /dev/null
+++ b/Mantle/MTLJSONAdapter.h
@@ -0,0 +1,172 @@
+//
+// MTLJSONAdapter.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-02-12.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+@class MTLModel;
+
+// A MTLModel object that supports being parsed from and serialized to JSON.
+@protocol MTLJSONSerializing
+@required
+
+// Specifies how to map property keys to different key paths in JSON.
+//
+// Subclasses overriding this method should combine their values with those of
+// `super`.
+//
+// Any property keys not present in the dictionary are assumed to match the JSON
+// key that should be used. Any keys associated with NSNull will not participate
+// in JSON serialization.
+//
+// Returns a dictionary mapping property keys to JSON key paths (as strings) or
+// NSNull values.
++ (NSDictionary *)JSONKeyPathsByPropertyKey;
+
+@optional
+
+// Specifies how to convert a JSON value to the given property key. If
+// reversible, the transformer will also be used to convert the property value
+// back to JSON.
+//
+// If the receiver implements a `+<key>JSONTransformer` method, MTLJSONAdapter
+// will use the result of that method instead.
+//
+// Returns a value transformer, or nil if no transformation should be performed.
++ (NSValueTransformer *)JSONTransformerForKey:(NSString *)key;
+
+// Overridden to parse the receiver as a different class, based on information
+// in the provided dictionary.
+//
+// This is mostly useful for class clusters, where the abstract base class would
+// be passed into -[MTLJSONAdapter initWithJSONDictionary:modelClass:], but
+// a subclass should be instantiated instead.
+//
+// JSONDictionary - The JSON dictionary that will be parsed.
+//
+// Returns the class that should be parsed (which may be the receiver), or nil
+// to abort parsing (e.g., if the data is invalid).
++ (Class)classForParsingJSONDictionary:(NSDictionary *)JSONDictionary;
+
+@end
+
+// The domain for errors originating from MTLJSONAdapter.
+extern NSString * const MTLJSONAdapterErrorDomain;
+
+// +classForParsingJSONDictionary: returned nil for the given dictionary.
+extern const NSInteger MTLJSONAdapterErrorNoClassFound;
+
+// The provided JSONDictionary is not valid.
+extern const NSInteger MTLJSONAdapterErrorInvalidJSONDictionary;
+
+// The model's implementation of +JSONKeyPathsByPropertyKey included a key which
+// does not actually exist in +propertyKeys.
+extern const NSInteger MTLJSONAdapterErrorInvalidJSONMapping;
+
+// Converts a MTLModel object to and from a JSON dictionary.
+@interface MTLJSONAdapter : NSObject
+
+// The model object that the receiver was initialized with, or that the receiver
+// parsed from a JSON dictionary.
+@property (nonatomic, strong, readonly) MTLModel<MTLJSONSerializing> *model;
+
+// Attempts to parse a JSON dictionary into a model object.
+//
+// modelClass - The MTLModel subclass to attempt to parse from the JSON.
+// This class must conform to <MTLJSONSerializing>. This
+// argument must not be nil.
+// JSONDictionary - A dictionary representing JSON data. This should match the
+// format returned by NSJSONSerialization. If this argument is
+// nil, the method returns nil.
+// error - If not NULL, this may be set to an error that occurs during
+// parsing or initializing an instance of `modelClass`.
+//
+// Returns an instance of `modelClass` upon success, or nil if a parsing error
+// occurred.
++ (id)modelOfClass:(Class)modelClass fromJSONDictionary:(NSDictionary *)JSONDictionary error:(NSError **)error;
+
+// Attempts to parse an array of JSON dictionary objects into a model objects
+// of a specific class.
+//
+// modelClass - The MTLModel subclass to attempt to parse from the JSON. This
+// class must conform to <MTLJSONSerializing>. This argument must
+// not be nil.
+// JSONArray - A array of dictionaries representing JSON data. This should
+// match the format returned by NSJSONSerialization. If this
+// argument is nil, the method returns nil.
+// error - If not NULL, this may be set to an error that occurs during
+// parsing or initializing an any of the instances of
+// `modelClass`.
+//
+// Returns an array of `modelClass` instances upon success, or nil if a parsing
+// error occurred.
++ (NSArray *)modelsOfClass:(Class)modelClass fromJSONArray:(NSArray *)JSONArray error:(NSError **)error;
+
+// Converts a model into a JSON representation.
+//
+// model - The model to use for JSON serialization. This argument must not be
+// nil.
+//
+// Returns a JSON dictionary, or nil if a serialization error occurred.
++ (NSDictionary *)JSONDictionaryFromModel:(MTLModel<MTLJSONSerializing> *)model;
+
+// Converts a array of models into a JSON representation.
+//
+// models - The array of models to use for JSON serialization. This argument
+// must not be nil.
+//
+// Returns a JSON array, or nil if a serialization error occurred for any
+// model.
++ (NSArray *)JSONArrayFromModels:(NSArray *)models;
+
+// Initializes the receiver by attempting to parse a JSON dictionary into
+// a model object.
+//
+// JSONDictionary - A dictionary representing JSON data. This should match the
+// format returned by NSJSONSerialization. If this argument is
+// nil, the method returns nil and an error with code
+// MTLJSONAdapterErrorInvalidJSONDictionary.
+// modelClass - The MTLModel subclass to attempt to parse from the JSON.
+// This class must conform to <MTLJSONSerializing>. This
+// argument must not be nil.
+// error - If not NULL, this may be set to an error that occurs during
+// parsing or initializing an instance of `modelClass`.
+//
+// Returns an initialized adapter upon success, or nil if a parsing error
+// occurred.
+- (id)initWithJSONDictionary:(NSDictionary *)JSONDictionary modelClass:(Class)modelClass error:(NSError **)error;
+
+// Initializes the receiver with an existing model.
+//
+// model - The model to use for JSON serialization. This argument must not be
+// nil.
+- (id)initWithModel:(MTLModel<MTLJSONSerializing> *)model;
+
+// Serializes the receiver's `model` into JSON.
+//
+// Returns a JSON dictionary, or nil if a serialization error occurred.
+- (NSDictionary *)JSONDictionary;
+
+// Looks up the JSON key path in the model's +propertyKeys.
+//
+// Subclasses may override this method to customize the adapter's seralizing
+// behavior. You should not call this method directly.
+//
+// key - The property key to retrieve the corresponding JSON key path for. This
+// argument must not be nil.
+//
+// Returns a key path to use, or nil to omit the property from JSON.
+- (NSString *)JSONKeyPathForPropertyKey:(NSString *)key;
+
+@end
+
+@interface MTLJSONAdapter (Deprecated)
+
++ (id)modelOfClass:(Class)modelClass fromJSONDictionary:(NSDictionary *)JSONDictionary __attribute__((deprecated("Replaced by +modelOfClass:fromJSONDictionary:error:")));
+- (id)initWithJSONDictionary:(NSDictionary *)JSONDictionary modelClass:(Class)modelClass __attribute__((deprecated("Replaced by -initWithJSONDictionary:modelClass:error:")));
+
+@end
diff --git a/Mantle/MTLJSONAdapter.m b/Mantle/MTLJSONAdapter.m
new file mode 100644
index 0000000..3cbcada
--- /dev/null
+++ b/Mantle/MTLJSONAdapter.m
@@ -0,0 +1,326 @@
+//
+// MTLJSONAdapter.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-02-12.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import "MTLJSONAdapter.h"
+#import "MTLModel.h"
+#import "MTLReflection.h"
+
+NSString * const MTLJSONAdapterErrorDomain = @"MTLJSONAdapterErrorDomain";
+const NSInteger MTLJSONAdapterErrorNoClassFound = 2;
+const NSInteger MTLJSONAdapterErrorInvalidJSONDictionary = 3;
+const NSInteger MTLJSONAdapterErrorInvalidJSONMapping = 4;
+
+// An exception was thrown and caught.
+const NSInteger MTLJSONAdapterErrorExceptionThrown = 1;
+
+// Associated with the NSException that was caught.
+static NSString * const MTLJSONAdapterThrownExceptionErrorKey = @"MTLJSONAdapterThrownException";
+
+@interface MTLJSONAdapter ()
+
+// The MTLModel subclass being parsed, or the class of `model` if parsing has
+// completed.
+@property (nonatomic, strong, readonly) Class modelClass;
+
+// A cached copy of the return value of +JSONKeyPathsByPropertyKey.
+@property (nonatomic, copy, readonly) NSDictionary *JSONKeyPathsByPropertyKey;
+
+// Looks up the NSValueTransformer that should be used for the given key.
+//
+// key - The property key to transform from or to. This argument must not be nil.
+//
+// Returns a transformer to use, or nil to not transform the property.
+- (NSValueTransformer *)JSONTransformerForKey:(NSString *)key;
+
+@end
+
+@implementation MTLJSONAdapter
+
+#pragma mark Convenience methods
+
++ (id)modelOfClass:(Class)modelClass fromJSONDictionary:(NSDictionary *)JSONDictionary error:(NSError **)error {
+ MTLJSONAdapter *adapter = [[self alloc] initWithJSONDictionary:JSONDictionary modelClass:modelClass error:error];
+ return adapter.model;
+}
+
++ (NSArray *)modelsOfClass:(Class)modelClass fromJSONArray:(NSArray *)JSONArray error:(NSError **)error {
+ if (JSONArray == nil || ![JSONArray isKindOfClass:NSArray.class]) {
+ if (error != NULL) {
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Missing JSON array", @""),
+ NSLocalizedFailureReasonErrorKey: [NSString stringWithFormat:NSLocalizedString(@"%@ could not be created because an invalid JSON array was provided: %@", @""), NSStringFromClass(modelClass), JSONArray.class],
+ };
+ *error = [NSError errorWithDomain:MTLJSONAdapterErrorDomain code:MTLJSONAdapterErrorInvalidJSONDictionary userInfo:userInfo];
+ }
+ return nil;
+ }
+
+ NSMutableArray *models = [NSMutableArray arrayWithCapacity:JSONArray.count];
+ for (NSDictionary *JSONDictionary in JSONArray){
+ MTLModel *model = [self modelOfClass:modelClass fromJSONDictionary:JSONDictionary error:error];
+
+ if (model == nil) return nil;
+
+ [models addObject:model];
+ }
+
+ return models;
+}
+
++ (NSDictionary *)JSONDictionaryFromModel:(MTLModel<MTLJSONSerializing> *)model {
+ MTLJSONAdapter *adapter = [[self alloc] initWithModel:model];
+ return adapter.JSONDictionary;
+}
+
++ (NSArray *)JSONArrayFromModels:(NSArray *)models {
+ NSParameterAssert(models != nil);
+ NSParameterAssert([models isKindOfClass:NSArray.class]);
+
+ NSMutableArray *JSONArray = [NSMutableArray arrayWithCapacity:models.count];
+ for (MTLModel<MTLJSONSerializing> *model in models) {
+ NSDictionary *JSONDictionary = [self JSONDictionaryFromModel:model];
+ if (JSONDictionary == nil) return nil;
+
+ [JSONArray addObject:JSONDictionary];
+ }
+
+ return JSONArray;
+}
+
+#pragma mark Lifecycle
+
+- (id)init {
+ NSAssert(NO, @"%@ must be initialized with a JSON dictionary or model object", self.class);
+ return nil;
+}
+
+- (id)initWithJSONDictionary:(NSDictionary *)JSONDictionary modelClass:(Class)modelClass error:(NSError **)error {
+ NSParameterAssert(modelClass != nil);
+ NSParameterAssert([modelClass isSubclassOfClass:MTLModel.class]);
+ NSParameterAssert([modelClass conformsToProtocol:@protocol(MTLJSONSerializing)]);
+
+ if (JSONDictionary == nil || ![JSONDictionary isKindOfClass:NSDictionary.class]) {
+ if (error != NULL) {
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Missing JSON dictionary", @""),
+ NSLocalizedFailureReasonErrorKey: [NSString stringWithFormat:NSLocalizedString(@"%@ could not be created because an invalid JSON dictionary was provided: %@", @""), NSStringFromClass(modelClass), JSONDictionary.class],
+ };
+ *error = [NSError errorWithDomain:MTLJSONAdapterErrorDomain code:MTLJSONAdapterErrorInvalidJSONDictionary userInfo:userInfo];
+ }
+ return nil;
+ }
+
+ if ([modelClass respondsToSelector:@selector(classForParsingJSONDictionary:)]) {
+ modelClass = [modelClass classForParsingJSONDictionary:JSONDictionary];
+ if (modelClass == nil) {
+ if (error != NULL) {
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not parse JSON", @""),
+ NSLocalizedFailureReasonErrorKey: NSLocalizedString(@"No model class could be found to parse the JSON dictionary.", @"")
+ };
+
+ *error = [NSError errorWithDomain:MTLJSONAdapterErrorDomain code:MTLJSONAdapterErrorNoClassFound userInfo:userInfo];
+ }
+
+ return nil;
+ }
+
+ NSAssert([modelClass isSubclassOfClass:MTLModel.class], @"Class %@ returned from +classForParsingJSONDictionary: is not a subclass of MTLModel", modelClass);
+ NSAssert([modelClass conformsToProtocol:@protocol(MTLJSONSerializing)], @"Class %@ returned from +classForParsingJSONDictionary: does not conform to <MTLJSONSerializing>", modelClass);
+ }
+
+ self = [super init];
+ if (self == nil) return nil;
+
+ _modelClass = modelClass;
+ _JSONKeyPathsByPropertyKey = [[modelClass JSONKeyPathsByPropertyKey] copy];
+
+ NSMutableDictionary *dictionaryValue = [[NSMutableDictionary alloc] initWithCapacity:JSONDictionary.count];
+
+ NSSet *propertyKeys = [self.modelClass propertyKeys];
+
+ for (NSString *JSONKeyPath in self.JSONKeyPathsByPropertyKey) {
+ if ([propertyKeys containsObject:JSONKeyPath]) continue;
+
+ if (error != NULL) {
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Invalid JSON mapping", nil),
+ NSLocalizedFailureReasonErrorKey: [NSString stringWithFormat:NSLocalizedString(@"%1$@ could not be parsed because its JSON mapping contains illegal property keys.", nil), modelClass]
+ };
+
+ *error = [NSError errorWithDomain:MTLJSONAdapterErrorDomain code:MTLJSONAdapterErrorInvalidJSONMapping userInfo:userInfo];
+ }
+
+ return nil;
+ }
+
+ for (NSString *propertyKey in propertyKeys) {
+ NSString *JSONKeyPath = [self JSONKeyPathForPropertyKey:propertyKey];
+ if (JSONKeyPath == nil) continue;
+
+ id value;
+ @try {
+ value = [JSONDictionary valueForKeyPath:JSONKeyPath];
+ } @catch (NSException *ex) {
+ if (error != NULL) {
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Invalid JSON dictionary", nil),
+ NSLocalizedFailureReasonErrorKey: [NSString stringWithFormat:NSLocalizedString(@"%1$@ could not be parsed because an invalid JSON dictionary was provided for key path \"%2$@\"", nil), modelClass, JSONKeyPath],
+ MTLJSONAdapterThrownExceptionErrorKey: ex
+ };
+
+ *error = [NSError errorWithDomain:MTLJSONAdapterErrorDomain code:MTLJSONAdapterErrorInvalidJSONDictionary userInfo:userInfo];
+ }
+
+ return nil;
+ }
+
+ if (value == nil) continue;
+
+ @try {
+ NSValueTransformer *transformer = [self JSONTransformerForKey:propertyKey];
+ if (transformer != nil) {
+ // Map NSNull -> nil for the transformer, and then back for the
+ // dictionary we're going to insert into.
+ if ([value isEqual:NSNull.null]) value = nil;
+ value = [transformer transformedValue:value] ?: NSNull.null;
+ }
+
+ dictionaryValue[propertyKey] = value;
+ } @catch (NSException *ex) {
+ NSLog(@"*** Caught exception %@ parsing JSON key path \"%@\" from: %@", ex, JSONKeyPath, JSONDictionary);
+
+ // Fail fast in Debug builds.
+ #if DEBUG
+ @throw ex;
+ #else
+ if (error != NULL) {
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: ex.description,
+ NSLocalizedFailureReasonErrorKey: ex.reason,
+ MTLJSONAdapterThrownExceptionErrorKey: ex
+ };
+
+ *error = [NSError errorWithDomain:MTLJSONAdapterErrorDomain code:MTLJSONAdapterErrorExceptionThrown userInfo:userInfo];
+ }
+
+ return nil;
+ #endif
+ }
+ }
+
+ _model = [self.modelClass modelWithDictionary:dictionaryValue error:error];
+ if (_model == nil) return nil;
+
+ return self;
+}
+
+- (id)initWithModel:(MTLModel<MTLJSONSerializing> *)model {
+ NSParameterAssert(model != nil);
+
+ self = [super init];
+ if (self == nil) return nil;
+
+ _model = model;
+ _modelClass = model.class;
+ _JSONKeyPathsByPropertyKey = [[model.class JSONKeyPathsByPropertyKey] copy];
+
+ return self;
+}
+
+#pragma mark Serialization
+
+- (NSDictionary *)JSONDictionary {
+ NSDictionary *dictionaryValue = self.model.dictionaryValue;
+ NSMutableDictionary *JSONDictionary = [[NSMutableDictionary alloc] initWithCapacity:dictionaryValue.count];
+
+ [dictionaryValue enumerateKeysAndObjectsUsingBlock:^(NSString *propertyKey, id value, BOOL *stop) {
+ NSString *JSONKeyPath = [self JSONKeyPathForPropertyKey:propertyKey];
+ if (JSONKeyPath == nil) return;
+
+ NSValueTransformer *transformer = [self JSONTransformerForKey:propertyKey];
+ if ([transformer.class allowsReverseTransformation]) {
+ // Map NSNull -> nil for the transformer, and then back for the
+ // dictionaryValue we're going to insert into.
+ if ([value isEqual:NSNull.null]) value = nil;
+ value = [transformer reverseTransformedValue:value] ?: NSNull.null;
+ }
+
+ NSArray *keyPathComponents = [JSONKeyPath componentsSeparatedByString:@"."];
+
+ // Set up dictionaries at each step of the key path.
+ id obj = JSONDictionary;
+ for (NSString *component in keyPathComponents) {
+ if ([obj valueForKey:component] == nil) {
+ // Insert an empty mutable dictionary at this spot so that we
+ // can set the whole key path afterward.
+ [obj setValue:[NSMutableDictionary dictionary] forKey:component];
+ }
+
+ obj = [obj valueForKey:component];
+ }
+
+ [JSONDictionary setValue:value forKeyPath:JSONKeyPath];
+ }];
+
+ return JSONDictionary;
+}
+
+- (NSValueTransformer *)JSONTransformerForKey:(NSString *)key {
+ NSParameterAssert(key != nil);
+
+ SEL selector = MTLSelectorWithKeyPattern(key, "JSONTransformer");
+ if ([self.modelClass respondsToSelector:selector]) {
+ NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:[self.modelClass methodSignatureForSelector:selector]];
+ invocation.target = self.modelClass;
+ invocation.selector = selector;
+ [invocation invoke];
+
+ __unsafe_unretained id result = nil;
+ [invocation getReturnValue:&result];
+ return result;
+ }
+
+ if ([self.modelClass respondsToSelector:@selector(JSONTransformerForKey:)]) {
+ return [self.modelClass JSONTransformerForKey:key];
+ }
+
+ return nil;
+}
+
+- (NSString *)JSONKeyPathForPropertyKey:(NSString *)key {
+ NSParameterAssert(key != nil);
+
+ id JSONKeyPath = self.JSONKeyPathsByPropertyKey[key];
+ if ([JSONKeyPath isEqual:NSNull.null]) return nil;
+
+ if (JSONKeyPath == nil) {
+ return key;
+ } else {
+ return JSONKeyPath;
+ }
+}
+
+@end
+
+@implementation MTLJSONAdapter (Deprecated)
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-implementations"
+
++ (id)modelOfClass:(Class)modelClass fromJSONDictionary:(NSDictionary *)JSONDictionary {
+ return [self modelOfClass:modelClass fromJSONDictionary:JSONDictionary error:NULL];
+}
+
+- (id)initWithJSONDictionary:(NSDictionary *)JSONDictionary modelClass:(Class)modelClass {
+ return [self initWithJSONDictionary:JSONDictionary modelClass:modelClass error:NULL];
+}
+
+#pragma clang diagnostic pop
+
+@end
diff --git a/Mantle/MTLManagedObjectAdapter.h b/Mantle/MTLManagedObjectAdapter.h
new file mode 100644
index 0000000..11b2bcf
--- /dev/null
+++ b/Mantle/MTLManagedObjectAdapter.h
@@ -0,0 +1,215 @@
+//
+// MTLManagedObjectAdapter.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-03-29.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import <CoreData/CoreData.h>
+
+@class MTLModel;
+
+// A MTLModel object that supports being serialized to and from Core Data as an
+// NSManagedObject.
+@protocol MTLManagedObjectSerializing
+@required
+
+// The name of the Core Data entity that the receiver serializes to and
+// deserializes from.
+//
+// This method must not return nil.
++ (NSString *)managedObjectEntityName;
+
+// Specifies how to map property keys to different keys on the receiver's
+// +managedObjectEntity.
+//
+// Entity attributes will be mapped to and from the receiver's properties using
+// +entityAttributeTransformerForKey:. Entity relationships will be mapped to
+// and from MTLModel objects using +relationshipModelClassesByPropertyKey.
+// Fetched properties are not supported.
+//
+// Subclasses overriding this method should combine their values with those of
+// `super`.
+//
+// Any property keys not present in the dictionary are assumed to match the
+// entity key that should be used. Any keys associated with NSNull will not
+// participate in managed object serialization.
+//
+// Returns a dictionary mapping property keys to entity keys (as strings) or
+// NSNull values.
++ (NSDictionary *)managedObjectKeysByPropertyKey;
+
+@optional
+
+// Specifies a set of property keys used by the adapter to check for an already
+// existing managed object when converting the MTLModel to its related
+// NSManagedObject.
+//
+// The adapter will first map any keys provided by this method to the correct
+// keys in managedObjectKeysByPropertyKey.
+//
+// The adapter will then perform a fetch request in the provided context for a
+// managed object that matches the MTLModel's managedObjectEntityName and has
+// equal values set for the property keys on the MTLModel.
+//
+// The managed object returned by the fetch request will then be set with all
+// values from the MTLModel that the managed object is being converted from.
+//
+// If a property value of our MTLModel is yet another MTLModel which needs to be
+// converted to a managed object, the class for that MTLModel can also implement
+// this method to perform its own uniqing.
+//
+// For example:
+// 1. An MTLModel subclass has id_number = 10.
+// 2. An NSManagedObject accessible to the adapter's context has idnumber = 10.
+// 3. managedObjectKeysByPropertyKey returns @{@"id_number" : @"idnumber"}
+// 4. propertyKeysForManagedObjectUniquing returns
+// [NSSet setWithObject:@"id_number"];
+// 5. Then our fetch request may return this managed object (or another managed
+// object with idnumber = 10).
+//
+// NOTE: If multiple managed objects follow the same uniquing criteria only one
+// of them will be set with our MTLModel's values.
++ (NSSet *)propertyKeysForManagedObjectUniquing;
+
+// Specifies how to convert the given property key to a managed object
+// attribute. If reversible, the transformer will also be used to convert the
+// managed object attribute back to the property.
+//
+// If the receiver implements a `+<key>EntityAttributeTransformer` method,
+// MTLManagedObjectAdapter will use the result of that method instead.
+//
+// Returns a value transformer, or nil if no transformation should be performed.
++ (NSValueTransformer *)entityAttributeTransformerForKey:(NSString *)key;
+
+// Specifies the MTLModel subclasses that should be deserialized to the
+// receiver's property keys when a property key corresponds to an entity
+// relationship.
+//
+// In other words, the dictionary returned by this method is used to decode
+// managed object relationships into MTLModels (or NSArrays or NSSets thereof)
+// set on the receiver.
+//
+// If a property key is omitted from the returned dictionary, but present in
+// +managedObjectKeysByPropertyKey, and the receiver's +managedObjectEntity has
+// a relationship at the corresponding key, an exception will be thrown during
+// deserialization.
+//
+// Subclasses overriding this method should combine their values with those of
+// `super`.
+//
+// Returns a dictionary mapping property keys to the Class objects that should
+// be used.
++ (NSDictionary *)relationshipModelClassesByPropertyKey;
+
+// Overridden to deserialize a different class instead of the receiver, based on
+// information in the provided object.
+//
+// This is mostly useful for class clusters, where the abstract base class would
+// be passed into +[MTLManagedObjectAdapter
+// modelOfClass:fromManagedObject:error:], but a subclass should be instantiated
+// instead.
+//
+// managedObject - The object that will be deserialized.
+//
+// Returns the class that should be instantiated (which may be the receiver), or
+// nil to abort parsing (e.g., if the data is invalid).
++ (Class)classForDeserializingManagedObject:(NSManagedObject *)managedObject;
+
+// Overriden when merging the value of the given key on the receiver with the
+// value of the same key from the given `NSManagedObject` requires custom
+// handling.
+//
+// By default, this method is not implemented, and precedence will be given to
+// the value of the receiving model implicitly.
+//
+// When implemented, this method is called when an existing `NSManagedObject`
+// is found for the receiving model, before updating the `NSManagedObject`'s
+// properties.
+//
+// When implementing, you should use `+managedObjectKeysByPropertyKey` to map
+// the given `key` to the appropriate `NSManagedObject` property.
+- (void)mergeValueForKey:(NSString *)key fromManagedObject:(NSManagedObject *)managedObject;
+
+// Overriden when merging values on the receiver with the given
+// `NSManagedObject` requires custom handling.
+//
+// By default, this method is not implemented, and precedence will be given to
+// the values of the receiving model implicitly.
+//
+// When implemented, this method is called when an existing `NSManagedObject`
+// is found for the receiving model, before updating the `NSManagedObject`'s
+// properties.
+//
+// When implementing, you should use `+managedObjectKeysByPropertyKey` to map
+// the given `key` to the appropriate `NSManagedObject` property.
+//
+// If you have also implemented `mergeValueForKey:fromManagedObject:` you have
+// to make sure to call `mergeValueForKey:fromManagedObject:` from this method
+// when appropriate.
+- (void)mergeValuesForKeysFromManagedObject:(NSManagedObject *)managedObject;
+
+@end
+
+// The domain for errors originating from MTLManagedObjectAdapter.
+extern NSString * const MTLManagedObjectAdapterErrorDomain;
+
+// +classForDeserializingManagedObject: returned nil for the given object.
+extern const NSInteger MTLManagedObjectAdapterErrorNoClassFound;
+
+// An NSManagedObject failed to initialize.
+extern const NSInteger MTLManagedObjectAdapterErrorInitializationFailed;
+
+// The managed object key specified by +managedObjectKeysByPropertyKey does not
+// exist in the NSEntityDescription.
+extern const NSInteger MTLManagedObjectAdapterErrorInvalidManagedObjectKey;
+
+// The managed object property specified has a type that isn't supported by
+// MTLManagedObjectAdapter.
+extern const NSInteger MTLManagedObjectAdapterErrorUnsupportedManagedObjectPropertyType;
+
+// The fetch request to find an existing managed object based on
+// `+propertyKeysForManagedObjectUniquing` failed.
+extern const NSInteger MTLManagedObjectAdapterErrorUniqueFetchRequestFailed;
+
+// A MTLModel property cannot be serialized to or deserialized from an
+// NSManagedObject relationship.
+//
+// For a to-one relationship, this means that the property does not contain
+// a MTLModel, or the MTLModel does not conform to <MTLManagedObjectSerializing>.
+//
+// For a to-many relationship, this means that the property does not contain an
+// NSArray or NSSet of MTLModel<MTLManagedObjectSerializing> instances.
+extern const NSInteger MTLManagedObjectAdapterErrorUnsupportedRelationshipClass;
+
+// The model's implementation of +managedObjectKeysByPropertyKey included a key
+// which does not actually exist in +propertyKeys.
+extern const NSInteger MTLManagedObjectAdapterErrorInvalidManagedObjectMapping;
+
+// Converts a MTLModel object to and from an NSManagedObject.
+@interface MTLManagedObjectAdapter : NSObject
+
+// Attempts to deserialize an NSManagedObject into a MTLModel object.
+//
+// modelClass - The MTLModel subclass to return. This class must conform to
+// <MTLManagedObjectSerializing>. This argument must not be nil.
+// managedObject - The managed object to deserialize. If this argument is nil,
+// the method returns nil.
+// error - If not NULL, this may be set to an error that occurs during
+// deserialization or initializing an instance of `modelClass`.
+//
+// Returns an instance of `modelClass` upon success, or nil if an error
+// occurred.
++ (id)modelOfClass:(Class)modelClass fromManagedObject:(NSManagedObject *)managedObject error:(NSError **)error;
+
+// Serializes a MTLModel into an NSManagedObject.
+//
+// model - The model object to serialize. This argument must not be nil.
+// context - The context into which to insert the created managed object. This
+// argument must not be nil.
+// error - If not NULL, this may be set to an error that occurs during
+// serialization or insertion.
++ (id)managedObjectFromModel:(MTLModel<MTLManagedObjectSerializing> *)model insertingIntoContext:(NSManagedObjectContext *)context error:(NSError **)error;
+
+@end
diff --git a/Mantle/MTLManagedObjectAdapter.m b/Mantle/MTLManagedObjectAdapter.m
new file mode 100644
index 0000000..84235c1
--- /dev/null
+++ b/Mantle/MTLManagedObjectAdapter.m
@@ -0,0 +1,645 @@
+//
+// MTLManagedObjectAdapter.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-03-29.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import "MTLManagedObjectAdapter.h"
+#import "EXTScope.h"
+#import "MTLModel.h"
+#import "MTLReflection.h"
+#import "NSArray+MTLManipulationAdditions.h"
+
+NSString * const MTLManagedObjectAdapterErrorDomain = @"MTLManagedObjectAdapterErrorDomain";
+const NSInteger MTLManagedObjectAdapterErrorNoClassFound = 2;
+const NSInteger MTLManagedObjectAdapterErrorInitializationFailed = 3;
+const NSInteger MTLManagedObjectAdapterErrorInvalidManagedObjectKey = 4;
+const NSInteger MTLManagedObjectAdapterErrorUnsupportedManagedObjectPropertyType = 5;
+const NSInteger MTLManagedObjectAdapterErrorUnsupportedRelationshipClass = 6;
+const NSInteger MTLManagedObjectAdapterErrorUniqueFetchRequestFailed = 7;
+const NSInteger MTLManagedObjectAdapterErrorInvalidManagedObjectMapping = 8;
+
+// Performs the given block in the context's queue, if it has one.
+static id performInContext(NSManagedObjectContext *context, id (^block)(void)) {
+ if (context.concurrencyType == NSConfinementConcurrencyType) {
+ return block();
+ }
+
+ __block id result = nil;
+ [context performBlockAndWait:^{
+ result = block();
+ }];
+
+ return result;
+}
+
+@interface MTLManagedObjectAdapter ()
+
+// The MTLModel subclass being serialized or deserialized.
+@property (nonatomic, strong, readonly) Class modelClass;
+
+// A cached copy of the return value of +managedObjectKeysByPropertyKey.
+@property (nonatomic, copy, readonly) NSDictionary *managedObjectKeysByPropertyKey;
+
+// A cached copy of the return value of +relationshipModelClassesByPropertyKey.
+@property (nonatomic, copy, readonly) NSDictionary *relationshipModelClassesByPropertyKey;
+
+// Initializes the receiver to serialize or deserialize a MTLModel of the given
+// class.
+- (id)initWithModelClass:(Class)modelClass;
+
+// Invoked from +modelOfClass:fromManagedObject:processedObjects:error: after
+// the receiver's properties have been initialized.
+- (id)modelFromManagedObject:(NSManagedObject *)managedObject processedObjects:(CFMutableDictionaryRef)processedObjects error:(NSError **)error;
+
+// Performs the actual work of deserialization. This method is also invoked when
+// processing relationships, to create a new adapter (if needed) to handle them.
+//
+// `processedObjects` is a dictionary mapping NSManagedObjects to the MTLModels
+// that have been created so far. It should remain alive for the full process
+// of deserializing the top-level managed object.
++ (id)modelOfClass:(Class)modelClass fromManagedObject:(NSManagedObject *)managedObject processedObjects:(CFMutableDictionaryRef)processedObjects error:(NSError **)error;
+
+// Invoked from
+// +managedObjectFromModel:insertingIntoContext:processedObjects:error: after
+// the receiver's properties have been initialized.
+- (id)managedObjectFromModel:(MTLModel<MTLManagedObjectSerializing> *)model insertingIntoContext:(NSManagedObjectContext *)context processedObjects:(CFMutableDictionaryRef)processedObjects error:(NSError **)error;
+
+// Performs the actual work of serialization. This method is also invoked when
+// processing relationships, to create a new adapter (if needed) to handle them.
+//
+// `processedObjects` is a dictionary mapping MTLModels to the NSManagedObjects
+// that have been created so far. It should remain alive for the full process
+// of serializing the top-level MTLModel.
++ (id)managedObjectFromModel:(MTLModel<MTLManagedObjectSerializing> *)model insertingIntoContext:(NSManagedObjectContext *)context processedObjects:(CFMutableDictionaryRef)processedObjects error:(NSError **)error;
+
+// Looks up the NSValueTransformer that should be used for any attribute that
+// corresponds the given property key.
+//
+// key - The property key to transform from or to. This argument must not be nil.
+//
+// Returns a transformer to use, or nil to not transform the property.
+- (NSValueTransformer *)entityAttributeTransformerForKey:(NSString *)key;
+
+// Looks up the managed object key that corresponds to the given key.
+//
+// key - The property key to retrieve the corresponding managed object key for.
+// This argument must not be nil.
+//
+// Returns a key to use, or nil to omit the property from managed object
+// serialization.
+- (NSString *)managedObjectKeyForKey:(NSString *)key;
+
+// Looks at propertyKeysForManagedObjectUniquing and forms an NSPredicate
+// using the uniquing keys and the provided model.
+- (NSPredicate *)uniquingPredicateForModel:(MTLModel<MTLManagedObjectSerializing> *)model;
+
+@end
+
+@implementation MTLManagedObjectAdapter
+
+#pragma mark Lifecycle
+
+- (id)init {
+ NSAssert(NO, @"%@ should not be initialized using -init", self.class);
+ return nil;
+}
+
+- (id)initWithModelClass:(Class)modelClass {
+ NSParameterAssert(modelClass != nil);
+
+ self = [super init];
+ if (self == nil) return nil;
+
+ _modelClass = modelClass;
+ _managedObjectKeysByPropertyKey = [[modelClass managedObjectKeysByPropertyKey] copy];
+
+ if ([modelClass respondsToSelector:@selector(relationshipModelClassesByPropertyKey)]) {
+ _relationshipModelClassesByPropertyKey = [[modelClass relationshipModelClassesByPropertyKey] copy];
+ }
+
+ return self;
+}
+
+#pragma mark Serialization
+
+- (id)modelFromManagedObject:(NSManagedObject *)managedObject processedObjects:(CFMutableDictionaryRef)processedObjects error:(NSError **)error {
+ NSParameterAssert(managedObject != nil);
+ NSParameterAssert(processedObjects != nil);
+
+ NSEntityDescription *entity = managedObject.entity;
+ NSAssert(entity != nil, @"%@ returned a nil +entity", managedObject);
+
+ NSManagedObjectContext *context = managedObject.managedObjectContext;
+
+ NSDictionary *managedObjectProperties = entity.propertiesByName;
+ MTLModel *model = [[self.modelClass alloc] init];
+
+ // Pre-emptively consider this object processed, so that we don't get into
+ // any cycles when processing its relationships.
+ CFDictionaryAddValue(processedObjects, (__bridge void *)managedObject, (__bridge void *)model);
+
+ BOOL (^setValueForKey)(NSString *, id) = ^(NSString *key, id value) {
+ // Mark this as being autoreleased, because validateValue may return
+ // a new object to be stored in this variable (and we don't want ARC to
+ // double-free or leak the old or new values).
+ __autoreleasing id replaceableValue = value;
+ if (![model validateValue:&replaceableValue forKey:key error:error]) return NO;
+
+ [model setValue:replaceableValue forKey:key];
+ return YES;
+ };
+
+ for (NSString *propertyKey in [self.modelClass propertyKeys]) {
+ NSString *managedObjectKey = [self managedObjectKeyForKey:propertyKey];
+ if (managedObjectKey == nil) continue;
+
+ BOOL (^deserializeAttribute)(NSAttributeDescription *) = ^(NSAttributeDescription *attributeDescription) {
+ id value = performInContext(context, ^{
+ return [managedObject valueForKey:managedObjectKey];
+ });
+
+ NSValueTransformer *attributeTransformer = [self entityAttributeTransformerForKey:propertyKey];
+ if (attributeTransformer != nil) value = [attributeTransformer reverseTransformedValue:value];
+
+ return setValueForKey(propertyKey, value);
+ };
+
+ BOOL (^deserializeRelationship)(NSRelationshipDescription *) = ^(NSRelationshipDescription *relationshipDescription) {
+ Class nestedClass = self.relationshipModelClassesByPropertyKey[propertyKey];
+ if (nestedClass == nil) {
+ [NSException raise:NSInvalidArgumentException format:@"No class specified for decoding relationship at key \"%@\" in managed object %@", managedObjectKey, managedObject];
+ }
+
+ if ([relationshipDescription isToMany]) {
+ id models = performInContext(context, ^ id {
+ id relationshipCollection = [managedObject valueForKey:managedObjectKey];
+ NSMutableArray *models = [NSMutableArray arrayWithCapacity:[relationshipCollection count]];
+
+ for (NSManagedObject *nestedObject in relationshipCollection) {
+ MTLModel *model = [self.class modelOfClass:nestedClass fromManagedObject:nestedObject processedObjects:processedObjects error:error];
+ if (model == nil) return nil;
+
+ [models addObject:model];
+ }
+
+ return models;
+ });
+
+ if (models == nil) return NO;
+ if (![relationshipDescription isOrdered]) models = [NSSet setWithArray:models];
+
+ return setValueForKey(propertyKey, models);
+ } else {
+ NSManagedObject *nestedObject = performInContext(context, ^{
+ return [managedObject valueForKey:managedObjectKey];
+ });
+
+ if (nestedObject == nil) return YES;
+
+ MTLModel *model = [self.class modelOfClass:nestedClass fromManagedObject:nestedObject processedObjects:processedObjects error:error];
+ if (model == nil) return NO;
+
+ return setValueForKey(propertyKey, model);
+ }
+ };
+
+ BOOL (^deserializeProperty)(NSPropertyDescription *) = ^(NSPropertyDescription *propertyDescription) {
+ if (propertyDescription == nil) {
+ if (error != NULL) {
+ NSString *failureReason = [NSString stringWithFormat:NSLocalizedString(@"No property by name \"%@\" exists on the entity.", @""), managedObjectKey];
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not deserialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: failureReason,
+ };
+
+ *error = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorInvalidManagedObjectKey userInfo:userInfo];
+ }
+
+ return NO;
+ }
+
+ // Jump through some hoops to avoid referencing classes directly.
+ NSString *propertyClassName = NSStringFromClass(propertyDescription.class);
+ if ([propertyClassName isEqual:@"NSAttributeDescription"]) {
+ return deserializeAttribute((id)propertyDescription);
+ } else if ([propertyClassName isEqual:@"NSRelationshipDescription"]) {
+ return deserializeRelationship((id)propertyDescription);
+ } else {
+ if (error != NULL) {
+ NSString *failureReason = [NSString stringWithFormat:NSLocalizedString(@"Property descriptions of class %@ are unsupported.", @""), propertyClassName];
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not deserialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: failureReason,
+ };
+
+ *error = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorUnsupportedManagedObjectPropertyType userInfo:userInfo];
+ }
+
+ return NO;
+ }
+ };
+
+ if (!deserializeProperty(managedObjectProperties[managedObjectKey])) return nil;
+ }
+
+ return model;
+}
+
++ (id)modelOfClass:(Class)modelClass fromManagedObject:(NSManagedObject *)managedObject error:(NSError **)error {
+ NSSet *propertyKeys = [modelClass propertyKeys];
+
+ for (NSString *mappedPropertyKey in [modelClass managedObjectKeysByPropertyKey]) {
+ if ([propertyKeys containsObject:mappedPropertyKey]) continue;
+
+ if (error != NULL) {
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Invalid entity attribute mapping", nil),
+ NSLocalizedFailureReasonErrorKey: [NSString stringWithFormat:NSLocalizedString(@"%1$@ could not be parsed because its entity attribute mapping contains illegal property keys.", nil), modelClass]
+ };
+
+ *error = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorInvalidManagedObjectMapping userInfo:userInfo];
+ }
+
+ return nil;
+ }
+
+ CFMutableDictionaryRef processedObjects = CFDictionaryCreateMutable(NULL, 0, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks);
+ if (processedObjects == NULL) return nil;
+
+ @onExit {
+ CFRelease(processedObjects);
+ };
+
+ return [self modelOfClass:modelClass fromManagedObject:managedObject processedObjects:processedObjects error:error];
+}
+
++ (id)modelOfClass:(Class)modelClass fromManagedObject:(NSManagedObject *)managedObject processedObjects:(CFMutableDictionaryRef)processedObjects error:(NSError **)error {
+ NSParameterAssert(modelClass != nil);
+ NSParameterAssert(processedObjects != nil);
+
+ if (managedObject == nil) return nil;
+
+ const void *existingModel = CFDictionaryGetValue(processedObjects, (__bridge void *)managedObject);
+ if (existingModel != NULL) {
+ return (__bridge id)existingModel;
+ }
+
+ if ([modelClass respondsToSelector:@selector(classForDeserializingManagedObject:)]) {
+ modelClass = [modelClass classForDeserializingManagedObject:managedObject];
+ if (modelClass == nil) {
+ if (error != NULL) {
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not deserialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: NSLocalizedString(@"No model class could be found to deserialize the object.", @"")
+ };
+
+ *error = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorNoClassFound userInfo:userInfo];
+ }
+
+ return nil;
+ }
+ }
+
+ MTLManagedObjectAdapter *adapter = [[self alloc] initWithModelClass:modelClass];
+ return [adapter modelFromManagedObject:managedObject processedObjects:processedObjects error:error];
+}
+
+- (id)managedObjectFromModel:(MTLModel<MTLManagedObjectSerializing> *)model insertingIntoContext:(NSManagedObjectContext *)context processedObjects:(CFMutableDictionaryRef)processedObjects error:(NSError **)error {
+ NSParameterAssert(model != nil);
+ NSParameterAssert(context != nil);
+ NSParameterAssert(processedObjects != nil);
+
+ NSString *entityName = [model.class managedObjectEntityName];
+ NSAssert(entityName != nil, @"%@ returned a nil +managedObjectEntityName", model.class);
+
+ Class entityDescriptionClass = NSClassFromString(@"NSEntityDescription");
+ NSAssert(entityDescriptionClass != nil, @"CoreData.framework must be linked to use MTLManagedObjectAdapter");
+
+ Class fetchRequestClass = NSClassFromString(@"NSFetchRequest");
+ NSAssert(fetchRequestClass != nil, @"CoreData.framework must be linked to use MTLManagedObjectAdapter");
+
+ // If a uniquing predicate is provided, perform a fetch request to guarantee a unique managed object.
+ __block NSManagedObject *managedObject = nil;
+ NSPredicate *uniquingPredicate = [self uniquingPredicateForModel:model];
+
+ if (uniquingPredicate != nil) {
+ __block NSError *fetchRequestError = nil;
+ __block BOOL encountedError = NO;
+ managedObject = performInContext(context, ^ id {
+ NSFetchRequest *fetchRequest = [[fetchRequestClass alloc] init];
+ fetchRequest.entity = [entityDescriptionClass entityForName:entityName inManagedObjectContext:context];
+ fetchRequest.predicate = uniquingPredicate;
+ fetchRequest.returnsObjectsAsFaults = NO;
+ fetchRequest.fetchLimit = 1;
+
+ NSArray *results = [context executeFetchRequest:fetchRequest error:&fetchRequestError];
+
+ if (results == nil) {
+ encountedError = YES;
+ if (error != NULL) {
+ NSString *failureReason = [NSString stringWithFormat:NSLocalizedString(@"Failed to fetch a managed object for uniqing predicate \"%@\".", @""), uniquingPredicate];
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not serialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: failureReason,
+ };
+
+ fetchRequestError = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorUniqueFetchRequestFailed userInfo:userInfo];
+ }
+
+ return nil;
+ }
+
+ return results.mtl_firstObject;
+ });
+
+ if (encountedError && error != NULL) {
+ *error = fetchRequestError;
+ return nil;
+ }
+ }
+
+ if (managedObject == nil) {
+ managedObject = [entityDescriptionClass insertNewObjectForEntityForName:entityName inManagedObjectContext:context];
+ } else {
+ // Our CoreData store already has data for this model, we need to merge
+ [self mergeValuesOfModel:model forKeysFromManagedObject:managedObject];
+ }
+
+ if (managedObject == nil) {
+ if (error != NULL) {
+ NSString *failureReason = [NSString stringWithFormat:NSLocalizedString(@"Failed to initialize a managed object from entity named \"%@\".", @""), entityName];
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not serialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: failureReason,
+ };
+
+ *error = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorInitializationFailed userInfo:userInfo];
+ }
+
+ return nil;
+ }
+
+ // Assign all errors to this variable to work around a memory problem.
+ //
+ // See https://github.com/github/Mantle/pull/120 for more context.
+ __block NSError *tmpError;
+
+ // Pre-emptively consider this object processed, so that we don't get into
+ // any cycles when processing its relationships.
+ CFDictionaryAddValue(processedObjects, (__bridge void *)model, (__bridge void *)managedObject);
+
+ NSDictionary *dictionaryValue = model.dictionaryValue;
+ NSDictionary *managedObjectProperties = managedObject.entity.propertiesByName;
+
+ [dictionaryValue enumerateKeysAndObjectsUsingBlock:^(NSString *propertyKey, id value, BOOL *stop) {
+ NSString *managedObjectKey = [self managedObjectKeyForKey:propertyKey];
+ if (managedObjectKey == nil) return;
+ if ([value isEqual:NSNull.null]) value = nil;
+
+ BOOL (^serializeAttribute)(NSAttributeDescription *) = ^(NSAttributeDescription *attributeDescription) {
+ // Mark this as being autoreleased, because validateValue may return
+ // a new object to be stored in this variable (and we don't want ARC to
+ // double-free or leak the old or new values).
+ __autoreleasing id transformedValue = value;
+
+ NSValueTransformer *attributeTransformer = [self entityAttributeTransformerForKey:propertyKey];
+ if (attributeTransformer != nil) transformedValue = [attributeTransformer transformedValue:transformedValue];
+
+ if (![managedObject validateValue:&transformedValue forKey:managedObjectKey error:&tmpError]) return NO;
+ [managedObject setValue:transformedValue forKey:managedObjectKey];
+
+ return YES;
+ };
+
+ NSManagedObject * (^objectForRelationshipFromModel)(id) = ^ id (id model) {
+ if (![model isKindOfClass:MTLModel.class] || ![model conformsToProtocol:@protocol(MTLManagedObjectSerializing)]) {
+ NSString *failureReason = [NSString stringWithFormat:NSLocalizedString(@"Property of class %@ cannot be encoded into an NSManagedObject.", @""), [model class]];
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not serialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: failureReason
+ };
+
+ tmpError = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorUnsupportedRelationshipClass userInfo:userInfo];
+
+ return nil;
+ }
+
+ return [self.class managedObjectFromModel:model insertingIntoContext:context processedObjects:processedObjects error:&tmpError];
+ };
+
+ BOOL (^serializeRelationship)(NSRelationshipDescription *) = ^(NSRelationshipDescription *relationshipDescription) {
+ if (value == nil) return YES;
+
+ if ([relationshipDescription isToMany]) {
+ if (![value conformsToProtocol:@protocol(NSFastEnumeration)]) {
+ NSString *failureReason = [NSString stringWithFormat:NSLocalizedString(@"Property of class %@ cannot be encoded into a to-many relationship.", @""), [value class]];
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not serialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: failureReason
+ };
+
+ tmpError = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorUnsupportedRelationshipClass userInfo:userInfo];
+
+ return NO;
+ }
+
+ id relationshipCollection;
+ if ([relationshipDescription isOrdered]) {
+ relationshipCollection = [NSMutableOrderedSet orderedSet];
+ } else {
+ relationshipCollection = [NSMutableSet set];
+ }
+
+ for (MTLModel *model in value) {
+ NSManagedObject *nestedObject = objectForRelationshipFromModel(model);
+ if (nestedObject == nil) return NO;
+
+ [relationshipCollection addObject:nestedObject];
+ }
+
+ [managedObject setValue:relationshipCollection forKey:managedObjectKey];
+ } else {
+ NSManagedObject *nestedObject = objectForRelationshipFromModel(value);
+ if (nestedObject == nil) return NO;
+
+ [managedObject setValue:nestedObject forKey:managedObjectKey];
+ }
+
+ return YES;
+ };
+
+ BOOL (^serializeProperty)(NSPropertyDescription *) = ^(NSPropertyDescription *propertyDescription) {
+ if (propertyDescription == nil) {
+ NSString *failureReason = [NSString stringWithFormat:NSLocalizedString(@"No property by name \"%@\" exists on the entity.", @""), managedObjectKey];
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not serialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: failureReason
+ };
+
+ tmpError = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorInvalidManagedObjectKey userInfo:userInfo];
+
+ return NO;
+ }
+
+ // Jump through some hoops to avoid referencing classes directly.
+ NSString *propertyClassName = NSStringFromClass(propertyDescription.class);
+ if ([propertyClassName isEqual:@"NSAttributeDescription"]) {
+ return serializeAttribute((id)propertyDescription);
+ } else if ([propertyClassName isEqual:@"NSRelationshipDescription"]) {
+ return serializeRelationship((id)propertyDescription);
+ } else {
+ NSString *failureReason = [NSString stringWithFormat:NSLocalizedString(@"Property descriptions of class %@ are unsupported.", @""), propertyClassName];
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: NSLocalizedString(@"Could not serialize managed object", @""),
+ NSLocalizedFailureReasonErrorKey: failureReason
+ };
+
+ tmpError = [NSError errorWithDomain:MTLManagedObjectAdapterErrorDomain code:MTLManagedObjectAdapterErrorUnsupportedManagedObjectPropertyType userInfo:userInfo];
+
+ return NO;
+ }
+ };
+
+ if (!serializeProperty(managedObjectProperties[managedObjectKey])) {
+ performInContext(context, ^ id {
+ [context deleteObject:managedObject];
+ return nil;
+ });
+
+ managedObject = nil;
+ *stop = YES;
+ }
+ }];
+
+ if (managedObject != nil && ![managedObject validateForInsert:&tmpError]) {
+ managedObject = performInContext(context, ^ id {
+ [context deleteObject:managedObject];
+ return nil;
+ });
+ }
+
+ if (error != NULL) {
+ *error = tmpError;
+ }
+
+ return managedObject;
+}
+
++ (id)managedObjectFromModel:(MTLModel<MTLManagedObjectSerializing> *)model insertingIntoContext:(NSManagedObjectContext *)context error:(NSError **)error {
+ CFDictionaryKeyCallBacks keyCallbacks = kCFTypeDictionaryKeyCallBacks;
+
+ // Compare MTLModel keys using pointer equality, not -isEqual:.
+ keyCallbacks.equal = NULL;
+
+ CFMutableDictionaryRef processedObjects = CFDictionaryCreateMutable(NULL, 0, &keyCallbacks, &kCFTypeDictionaryValueCallBacks);
+ if (processedObjects == NULL) return nil;
+
+ @onExit {
+ CFRelease(processedObjects);
+ };
+
+ return [self managedObjectFromModel:model insertingIntoContext:context processedObjects:processedObjects error:error];
+}
+
++ (id)managedObjectFromModel:(MTLModel<MTLManagedObjectSerializing> *)model insertingIntoContext:(NSManagedObjectContext *)context processedObjects:(CFMutableDictionaryRef)processedObjects error:(NSError **)error {
+ NSParameterAssert(model != nil);
+ NSParameterAssert(context != nil);
+ NSParameterAssert(processedObjects != nil);
+
+ const void *existingManagedObject = CFDictionaryGetValue(processedObjects, (__bridge void *)model);
+ if (existingManagedObject != NULL) {
+ return (__bridge id)existingManagedObject;
+ }
+
+ MTLManagedObjectAdapter *adapter = [[self alloc] initWithModelClass:model.class];
+ return [adapter managedObjectFromModel:model insertingIntoContext:context processedObjects:processedObjects error:error];
+}
+
+- (NSValueTransformer *)entityAttributeTransformerForKey:(NSString *)key {
+ NSParameterAssert(key != nil);
+
+ SEL selector = MTLSelectorWithKeyPattern(key, "EntityAttributeTransformer");
+ if ([self.modelClass respondsToSelector:selector]) {
+ NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:[self.modelClass methodSignatureForSelector:selector]];
+ invocation.target = self.modelClass;
+ invocation.selector = selector;
+ [invocation invoke];
+
+ __unsafe_unretained id result = nil;
+ [invocation getReturnValue:&result];
+ return result;
+ }
+
+ if ([self.modelClass respondsToSelector:@selector(entityAttributeTransformerForKey:)]) {
+ return [self.modelClass entityAttributeTransformerForKey:key];
+ }
+
+ return nil;
+}
+
+- (NSString *)managedObjectKeyForKey:(NSString *)key {
+ NSParameterAssert(key != nil);
+
+ id managedObjectKey = self.managedObjectKeysByPropertyKey[key];
+ if ([managedObjectKey isEqual:NSNull.null]) return nil;
+
+ if (managedObjectKey == nil) {
+ return key;
+ } else {
+ return managedObjectKey;
+ }
+}
+
+- (void)mergeValueOfModel:(MTLModel<MTLManagedObjectSerializing> *)model forKey:(NSString *)key fromManagedObject:(NSManagedObject *)managedObject {
+ [model mergeValueForKey:key fromManagedObject:managedObject];
+}
+
+- (void)mergeValuesOfModel:(MTLModel<MTLManagedObjectSerializing> *)model forKeysFromManagedObject:(NSManagedObject *)managedObject {
+ if ([model respondsToSelector:@selector(mergeValuesForKeysFromManagedObject:)]) {
+ [model mergeValuesForKeysFromManagedObject:managedObject];
+ } else if ([model respondsToSelector:@selector(mergeValueForKey:fromManagedObject:)]) {
+ [[model.class managedObjectKeysByPropertyKey] enumerateKeysAndObjectsUsingBlock:^(NSString *key, NSString *managedObjectKey, BOOL *stop) {
+ [self mergeValueOfModel:model forKey:key fromManagedObject:managedObject];
+ }];
+ }
+}
+
+- (NSPredicate *)uniquingPredicateForModel:(MTLModel<MTLManagedObjectSerializing> *)model {
+ if (![self.modelClass respondsToSelector:@selector(propertyKeysForManagedObjectUniquing)]) return nil;
+
+ NSSet *propertyKeys = [self.modelClass propertyKeysForManagedObjectUniquing];
+
+ if (propertyKeys == nil) return nil;
+
+ NSAssert(propertyKeys.count > 0, @"+propertyKeysForManagedObjectUniquing must not be empty.");
+
+ NSMutableArray *subpredicates = [NSMutableArray array];
+ for (NSString *propertyKey in propertyKeys) {
+ NSString *managedObjectKey = [self managedObjectKeyForKey:propertyKey];
+
+ NSAssert(managedObjectKey != nil, @"%@ must map to a managed object key.", propertyKey);
+
+ id transformedValue = [model valueForKeyPath:propertyKey];
+
+ NSValueTransformer *attributeTransformer = [self entityAttributeTransformerForKey:propertyKey];
+ if (attributeTransformer != nil) transformedValue = [attributeTransformer transformedValue:transformedValue];
+
+ NSPredicate *subpredicate = [NSPredicate predicateWithFormat:@"%K == %@", managedObjectKey, transformedValue];
+ [subpredicates addObject:subpredicate];
+ }
+
+ return [NSCompoundPredicate andPredicateWithSubpredicates:subpredicates];
+}
+
+@end
diff --git a/Mantle/MTLModel+NSCoding.h b/Mantle/MTLModel+NSCoding.h
new file mode 100644
index 0000000..94b8f7b
--- /dev/null
+++ b/Mantle/MTLModel+NSCoding.h
@@ -0,0 +1,128 @@
+//
+// 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
diff --git a/Mantle/MTLModel+NSCoding.m b/Mantle/MTLModel+NSCoding.m
new file mode 100644
index 0000000..852f5ae
--- /dev/null
+++ b/Mantle/MTLModel+NSCoding.m
@@ -0,0 +1,267 @@
+//
+// MTLModel+NSCoding.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-02-12.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import "MTLModel+NSCoding.h"
+#import "EXTRuntimeExtensions.h"
+#import "EXTScope.h"
+#import "MTLReflection.h"
+#import <objc/runtime.h>
+
+// Used in archives to store the modelVersion of the archived instance.
+static NSString * const MTLModelVersionKey = @"MTLModelVersion";
+
+// Used to cache the reflection performed in +allowedSecureCodingClassesByPropertyKey.
+static void *MTLModelCachedAllowedClassesKey = &MTLModelCachedAllowedClassesKey;
+
+// Returns whether the given NSCoder requires secure coding.
+static BOOL coderRequiresSecureCoding(NSCoder *coder) {
+ SEL requiresSecureCodingSelector = @selector(requiresSecureCoding);
+
+ // Only invoke the method if it's implemented (i.e., only on OS X 10.8+ and
+ // iOS 6+).
+ if (![coder respondsToSelector:requiresSecureCodingSelector]) return NO;
+
+ BOOL (*requiresSecureCodingIMP)(NSCoder *, SEL) = (__typeof__(requiresSecureCodingIMP))[coder methodForSelector:requiresSecureCodingSelector];
+ if (requiresSecureCodingIMP == NULL) return NO;
+
+ return requiresSecureCodingIMP(coder, requiresSecureCodingSelector);
+}
+
+// Returns all of the given class' encodable property keys (those that will not
+// be excluded from archives).
+static NSSet *encodablePropertyKeysForClass(Class modelClass) {
+ return [[modelClass encodingBehaviorsByPropertyKey] keysOfEntriesPassingTest:^ BOOL (NSString *propertyKey, NSNumber *behavior, BOOL *stop) {
+ return behavior.unsignedIntegerValue != MTLModelEncodingBehaviorExcluded;
+ }];
+}
+
+// Verifies that all of the specified class' encodable property keys are present
+// in +allowedSecureCodingClassesByPropertyKey, and throws an exception if not.
+static void verifyAllowedClassesByPropertyKey(Class modelClass) {
+ NSDictionary *allowedClasses = [modelClass allowedSecureCodingClassesByPropertyKey];
+
+ NSMutableSet *specifiedPropertyKeys = [[NSMutableSet alloc] initWithArray:allowedClasses.allKeys];
+ [specifiedPropertyKeys minusSet:encodablePropertyKeysForClass(modelClass)];
+
+ if (specifiedPropertyKeys.count > 0) {
+ [NSException raise:NSInvalidArgumentException format:@"Cannot encode %@ securely, because keys are missing from +allowedSecureCodingClassesByPropertyKey: %@", modelClass, specifiedPropertyKeys];
+ }
+}
+
+@implementation MTLModel (NSCoding)
+
+#pragma mark Versioning
+
++ (NSUInteger)modelVersion {
+ return 0;
+}
+
+#pragma mark Encoding Behaviors
+
++ (NSDictionary *)encodingBehaviorsByPropertyKey {
+ NSSet *propertyKeys = self.propertyKeys;
+ NSMutableDictionary *behaviors = [[NSMutableDictionary alloc] initWithCapacity:propertyKeys.count];
+
+ for (NSString *key in propertyKeys) {
+ objc_property_t property = class_getProperty(self, key.UTF8String);
+ NSAssert(property != NULL, @"Could not find property \"%@\" on %@", key, self);
+
+ mtl_propertyAttributes *attributes = mtl_copyPropertyAttributes(property);
+ @onExit {
+ free(attributes);
+ };
+
+ MTLModelEncodingBehavior behavior = (attributes->weak ? MTLModelEncodingBehaviorConditional : MTLModelEncodingBehaviorUnconditional);
+ behaviors[key] = @(behavior);
+ }
+
+ return behaviors;
+}
+
++ (NSDictionary *)allowedSecureCodingClassesByPropertyKey {
+ NSDictionary *cachedClasses = objc_getAssociatedObject(self, MTLModelCachedAllowedClassesKey);
+ if (cachedClasses != nil) return cachedClasses;
+
+ // Get all property keys that could potentially be encoded.
+ NSSet *propertyKeys = [self.encodingBehaviorsByPropertyKey keysOfEntriesPassingTest:^ BOOL (NSString *propertyKey, NSNumber *behavior, BOOL *stop) {
+ return behavior.unsignedIntegerValue != MTLModelEncodingBehaviorExcluded;
+ }];
+
+ NSMutableDictionary *allowedClasses = [[NSMutableDictionary alloc] initWithCapacity:propertyKeys.count];
+
+ for (NSString *key in propertyKeys) {
+ objc_property_t property = class_getProperty(self, key.UTF8String);
+ NSAssert(property != NULL, @"Could not find property \"%@\" on %@", key, self);
+
+ mtl_propertyAttributes *attributes = mtl_copyPropertyAttributes(property);
+ @onExit {
+ free(attributes);
+ };
+
+ // If the property is not of object or class type, assume that it's
+ // a primitive which would be boxed into an NSValue.
+ if (attributes->type[0] != '@' && attributes->type[0] != '#') {
+ allowedClasses[key] = @[ NSValue.class ];
+ continue;
+ }
+
+ // Omit this property from the dictionary if its class isn't known.
+ if (attributes->objectClass != nil) {
+ allowedClasses[key] = @[ attributes->objectClass ];
+ }
+ }
+
+ // It doesn't really matter if we replace another thread's work, since we do
+ // it atomically and the result should be the same.
+ objc_setAssociatedObject(self, MTLModelCachedAllowedClassesKey, allowedClasses, OBJC_ASSOCIATION_COPY);
+
+ return allowedClasses;
+}
+
+- (id)decodeValueForKey:(NSString *)key withCoder:(NSCoder *)coder modelVersion:(NSUInteger)modelVersion {
+ NSParameterAssert(key != nil);
+ NSParameterAssert(coder != nil);
+
+ SEL selector = MTLSelectorWithCapitalizedKeyPattern("decode", key, "WithCoder:modelVersion:");
+ if ([self respondsToSelector:selector]) {
+ NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:[self methodSignatureForSelector:selector]];
+ invocation.target = self;
+ invocation.selector = selector;
+ [invocation setArgument:&coder atIndex:2];
+ [invocation setArgument:&modelVersion atIndex:3];
+ [invocation invoke];
+
+ __unsafe_unretained id result = nil;
+ [invocation getReturnValue:&result];
+ return result;
+ }
+
+ @try {
+ if (coderRequiresSecureCoding(coder)) {
+ NSArray *allowedClasses = self.class.allowedSecureCodingClassesByPropertyKey[key];
+ NSAssert(allowedClasses != nil, @"No allowed classes specified for securely decoding key \"%@\" on %@", key, self.class);
+
+ return [coder decodeObjectOfClasses:[NSSet setWithArray:allowedClasses] forKey:key];
+ } else {
+ return [coder decodeObjectForKey:key];
+ }
+ } @catch (NSException *ex) {
+ NSLog(@"*** Caught exception decoding value for key \"%@\" on class %@: %@", key, self.class, ex);
+ @throw ex;
+ }
+}
+
+#pragma mark NSCoding
+
+- (instancetype)initWithCoder:(NSCoder *)coder {
+ BOOL requiresSecureCoding = coderRequiresSecureCoding(coder);
+ NSNumber *version = nil;
+ if (requiresSecureCoding) {
+ version = [coder decodeObjectOfClass:NSNumber.class forKey:MTLModelVersionKey];
+ } else {
+ version = [coder decodeObjectForKey:MTLModelVersionKey];
+ }
+
+ if (version == nil) {
+ NSLog(@"Warning: decoding an archive of %@ without a version, assuming 0", self.class);
+ } else if (version.unsignedIntegerValue > self.class.modelVersion) {
+ // Don't try to decode newer versions.
+ return nil;
+ }
+
+ if (requiresSecureCoding) {
+ verifyAllowedClassesByPropertyKey(self.class);
+ } else {
+ // Handle the old archive format.
+ NSDictionary *externalRepresentation = [coder decodeObjectForKey:@"externalRepresentation"];
+ if (externalRepresentation != nil) {
+ NSAssert([self.class methodForSelector:@selector(dictionaryValueFromArchivedExternalRepresentation:version:)] != [MTLModel methodForSelector:@selector(dictionaryValueFromArchivedExternalRepresentation:version:)], @"Decoded an old archive of %@ that contains an externalRepresentation, but +dictionaryValueFromArchivedExternalRepresentation:version: is not overridden to handle it", self.class);
+
+ NSDictionary *dictionaryValue = [self.class dictionaryValueFromArchivedExternalRepresentation:externalRepresentation version:version.unsignedIntegerValue];
+ if (dictionaryValue == nil) return nil;
+
+ NSError *error = nil;
+ self = [self initWithDictionary:dictionaryValue error:&error];
+ if (self == nil) NSLog(@"*** Could not decode old %@ archive: %@", self.class, error);
+
+ return self;
+ }
+ }
+
+ NSSet *propertyKeys = self.class.propertyKeys;
+ NSMutableDictionary *dictionaryValue = [[NSMutableDictionary alloc] initWithCapacity:propertyKeys.count];
+
+ for (NSString *key in propertyKeys) {
+ id value = [self decodeValueForKey:key withCoder:coder modelVersion:version.unsignedIntegerValue];
+ if (value == nil) continue;
+
+ dictionaryValue[key] = value;
+ }
+
+ NSError *error = nil;
+ self = [self initWithDictionary:dictionaryValue error:&error];
+ if (self == nil) NSLog(@"*** Could not unarchive %@: %@", self.class, error);
+
+ return self;
+}
+
+- (void)encodeWithCoder:(NSCoder *)coder {
+ if (coderRequiresSecureCoding(coder)) verifyAllowedClassesByPropertyKey(self.class);
+
+ [coder encodeObject:@(self.class.modelVersion) forKey:MTLModelVersionKey];
+
+ NSDictionary *encodingBehaviors = self.class.encodingBehaviorsByPropertyKey;
+ [self.dictionaryValue enumerateKeysAndObjectsUsingBlock:^(NSString *key, id value, BOOL *stop) {
+ @try {
+ // Skip nil values.
+ if ([value isEqual:NSNull.null]) return;
+
+ switch ([encodingBehaviors[key] unsignedIntegerValue]) {
+ // This will also match a nil behavior.
+ case MTLModelEncodingBehaviorExcluded:
+ break;
+
+ case MTLModelEncodingBehaviorUnconditional:
+ [coder encodeObject:value forKey:key];
+ break;
+
+ case MTLModelEncodingBehaviorConditional:
+ [coder encodeConditionalObject:value forKey:key];
+ break;
+
+ default:
+ NSAssert(NO, @"Unrecognized encoding behavior %@ on class %@ for key \"%@\"", self.class, encodingBehaviors[key], key);
+ }
+ } @catch (NSException *ex) {
+ NSLog(@"*** Caught exception encoding value for key \"%@\" on class %@: %@", key, self.class, ex);
+ @throw ex;
+ }
+ }];
+}
+
+#pragma mark NSSecureCoding
+
++ (BOOL)supportsSecureCoding {
+ // Disable secure coding support by default, so subclasses are forced to
+ // opt-in by conforming to the protocol and overriding this method.
+ //
+ // We only implement this method because XPC complains if a subclass tries
+ // to implement it but does not override -initWithCoder:. See
+ // https://github.com/github/Mantle/issues/74.
+ return NO;
+}
+
+@end
+
+@implementation MTLModel (OldArchiveSupport)
+
++ (NSDictionary *)dictionaryValueFromArchivedExternalRepresentation:(NSDictionary *)externalRepresentation version:(NSUInteger)fromVersion {
+ return nil;
+}
+
+@end
diff --git a/Mantle/MTLModel.h b/Mantle/MTLModel.h
new file mode 100644
index 0000000..7eb06f1
--- /dev/null
+++ b/Mantle/MTLModel.h
@@ -0,0 +1,121 @@
+//
+// MTLModel.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-11.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+// An abstract base class for model objects, using reflection to provide
+// sensible default behaviors.
+//
+// The default implementations of <NSCopying>, -hash, and -isEqual: make use of
+// the +propertyKeys method.
+@interface MTLModel : NSObject <NSCopying>
+
+// Returns a new instance of the receiver initialized using
+// -initWithDictionary:error:.
++ (instancetype)modelWithDictionary:(NSDictionary *)dictionaryValue error:(NSError **)error;
+
+// Initializes the receiver with default values.
+//
+// This is the designated initializer for this class.
+- (instancetype)init;
+
+// Initializes the receiver using key-value coding, setting the keys and values
+// in the given dictionary.
+//
+// dictionaryValue - Property keys and values to set on the receiver. Any NSNull
+// values will be converted to nil before being used. KVC
+// validation methods will automatically be invoked for all of
+// the properties given. If nil, this method is equivalent to
+// -init.
+// error - If not NULL, this may be set to any error that occurs
+// (like a KVC validation error).
+//
+// Returns an initialized model object, or nil if validation failed.
+- (instancetype)initWithDictionary:(NSDictionary *)dictionaryValue error:(NSError **)error;
+
+// Returns the keys for all @property declarations, except for `readonly`
+// properties without ivars, or properties on MTLModel itself.
++ (NSSet *)propertyKeys;
+
+// A dictionary representing the properties of the receiver.
+//
+// The default implementation combines the values corresponding to all
+// +propertyKeys into a dictionary, with any nil values represented by NSNull.
+//
+// This property must never be nil.
+@property (nonatomic, copy, readonly) NSDictionary *dictionaryValue;
+
+// Merges the value of the given key on the receiver with the value of the same
+// key from the given model object, giving precedence to the other model object.
+//
+// By default, this method looks for a `-merge<Key>FromModel:` method on the
+// receiver, and invokes it if found. If not found, and `model` is not nil, the
+// value for the given key is taken from `model`.
+- (void)mergeValueForKey:(NSString *)key fromModel:(MTLModel *)model;
+
+// Merges the values of the given model object into the receiver, using
+// -mergeValueForKey:fromModel: for each key in +propertyKeys.
+//
+// `model` must be an instance of the receiver's class or a subclass thereof.
+- (void)mergeValuesForKeysFromModel:(MTLModel *)model;
+
+// Compares the receiver with another object for equality.
+//
+// The default implementation is equivalent to comparing both models'
+// -dictionaryValue.
+//
+// Note that this may lead to infinite loops if the receiver holds a circular
+// reference to another MTLModel and both use the default behavior.
+// It is recommended to override -isEqual: in this scenario.
+- (BOOL)isEqual:(id)object;
+
+// A string that describes the contents of the receiver.
+//
+// The default implementation is based on the receiver's class and its
+// -dictionaryValue.
+//
+// Note that this may lead to infinite loops if the receiver holds a circular
+// reference to another MTLModel and both use the default behavior.
+// It is recommended to override -description in this scenario.
+- (NSString *)description;
+
+@end
+
+// Implements validation logic for MTLModel.
+@interface MTLModel (Validation)
+
+// Validates the model.
+//
+// The default implementation simply invokes -validateValue:forKey:error: with
+// all +propertyKeys and their current value. If -validateValue:forKey:error:
+// returns a new value, the property is set to that new value.
+//
+// error - If not NULL, this may be set to any error that occurs during
+// validation
+//
+// Returns YES if the model is valid, or NO if the validation failed.
+- (BOOL)validate:(NSError **)error;
+
+@end
+
+@interface MTLModel (Unavailable)
+
++ (instancetype)modelWithDictionary:(NSDictionary *)dictionaryValue __attribute__((deprecated("Replaced by +modelWithDictionary:error:")));
+- (instancetype)initWithDictionary:(NSDictionary *)dictionaryValue __attribute__((deprecated("Replaced by -initWithDictionary:error:")));
+
++ (instancetype)modelWithExternalRepresentation:(NSDictionary *)externalRepresentation __attribute__((deprecated("Replaced by -[MTLJSONAdapter initWithJSONDictionary:modelClass:]")));
+- (instancetype)initWithExternalRepresentation:(NSDictionary *)externalRepresentation __attribute__((deprecated("Replaced by -[MTLJSONAdapter initWithJSONDictionary:modelClass:]")));
+
+@property (nonatomic, copy, readonly) NSDictionary *externalRepresentation __attribute__((deprecated("Replaced by MTLJSONAdapter.JSONDictionary")));
+
++ (NSDictionary *)externalRepresentationKeyPathsByPropertyKey __attribute__((deprecated("Replaced by +JSONKeyPathsByPropertyKey in <MTLJSONSerializing>")));
++ (NSValueTransformer *)transformerForKey:(NSString *)key __attribute__((deprecated("Replaced by +JSONTransformerForKey: in <MTLJSONSerializing>")));
+
++ (NSDictionary *)migrateExternalRepresentation:(NSDictionary *)externalRepresentation fromVersion:(NSUInteger)fromVersion __attribute__((deprecated("Replaced by -decodeValueForKey:withCoder:modelVersion:")));
+
+@end
diff --git a/Mantle/MTLModel.m b/Mantle/MTLModel.m
new file mode 100644
index 0000000..2ef60fe
--- /dev/null
+++ b/Mantle/MTLModel.m
@@ -0,0 +1,245 @@
+//
+// MTLModel.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-11.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import "NSError+MTLModelException.h"
+#import "MTLModel.h"
+#import "EXTRuntimeExtensions.h"
+#import "EXTScope.h"
+#import "MTLReflection.h"
+#import <objc/runtime.h>
+
+// This coupling is needed for backwards compatibility in MTLModel's deprecated
+// methods.
+#import "MTLJSONAdapter.h"
+#import "MTLModel+NSCoding.h"
+
+// Used to cache the reflection performed in +propertyKeys.
+static void *MTLModelCachedPropertyKeysKey = &MTLModelCachedPropertyKeysKey;
+
+// Validates a value for an object and sets it if necessary.
+//
+// obj - The object for which the value is being validated. This value
+// must not be nil.
+// key - The name of one of `obj`s properties. This value must not be
+// nil.
+// value - The new value for the property identified by `key`.
+// forceUpdate - If set to `YES`, the value is being updated even if validating
+// it did not change it.
+// error - If not NULL, this may be set to any error that occurs during
+// validation
+//
+// Returns YES if `value` could be validated and set, or NO if an error
+// occurred.
+static BOOL MTLValidateAndSetValue(id obj, NSString *key, id value, BOOL forceUpdate, NSError **error) {
+ // Mark this as being autoreleased, because validateValue may return
+ // a new object to be stored in this variable (and we don't want ARC to
+ // double-free or leak the old or new values).
+ __autoreleasing id validatedValue = value;
+
+ @try {
+ if (![obj validateValue:&validatedValue forKey:key error:error]) return NO;
+
+ if (forceUpdate || value != validatedValue) {
+ [obj setValue:validatedValue forKey:key];
+ }
+
+ return YES;
+ } @catch (NSException *ex) {
+ NSLog(@"*** Caught exception setting key \"%@\" : %@", key, ex);
+
+ // Fail fast in Debug builds.
+ #if DEBUG
+ @throw ex;
+ #else
+ if (error != NULL) {
+ *error = [NSError mtl_modelErrorWithException:ex];
+ }
+
+ return NO;
+ #endif
+ }
+}
+
+@interface MTLModel ()
+
+// Enumerates all properties of the receiver's class hierarchy, starting at the
+// receiver, and continuing up until (but not including) MTLModel.
+//
+// The given block will be invoked multiple times for any properties declared on
+// multiple classes in the hierarchy.
++ (void)enumeratePropertiesUsingBlock:(void (^)(objc_property_t property, BOOL *stop))block;
+
+@end
+
+@implementation MTLModel
+
+#pragma mark Lifecycle
+
++ (instancetype)modelWithDictionary:(NSDictionary *)dictionary error:(NSError **)error {
+ return [[self alloc] initWithDictionary:dictionary error:error];
+}
+
+- (instancetype)init {
+ // Nothing special by default, but we have a declaration in the header.
+ return [super init];
+}
+
+- (instancetype)initWithDictionary:(NSDictionary *)dictionary error:(NSError **)error {
+ self = [self init];
+ if (self == nil) return nil;
+
+ for (NSString *key in dictionary) {
+ // Mark this as being autoreleased, because validateValue may return
+ // a new object to be stored in this variable (and we don't want ARC to
+ // double-free or leak the old or new values).
+ __autoreleasing id value = [dictionary objectForKey:key];
+
+ if ([value isEqual:NSNull.null]) value = nil;
+
+ BOOL success = MTLValidateAndSetValue(self, key, value, YES, error);
+ if (!success) return nil;
+ }
+
+ return self;
+}
+
+#pragma mark Reflection
+
++ (void)enumeratePropertiesUsingBlock:(void (^)(objc_property_t property, BOOL *stop))block {
+ Class cls = self;
+ BOOL stop = NO;
+
+ while (!stop && ![cls isEqual:MTLModel.class]) {
+ unsigned count = 0;
+ objc_property_t *properties = class_copyPropertyList(cls, &count);
+
+ cls = cls.superclass;
+ if (properties == NULL) continue;
+
+ @onExit {
+ free(properties);
+ };
+
+ for (unsigned i = 0; i < count; i++) {
+ block(properties[i], &stop);
+ if (stop) break;
+ }
+ }
+}
+
++ (NSSet *)propertyKeys {
+ NSSet *cachedKeys = objc_getAssociatedObject(self, MTLModelCachedPropertyKeysKey);
+ if (cachedKeys != nil) return cachedKeys;
+
+ NSMutableSet *keys = [NSMutableSet set];
+
+ [self enumeratePropertiesUsingBlock:^(objc_property_t property, BOOL *stop) {
+ mtl_propertyAttributes *attributes = mtl_copyPropertyAttributes(property);
+ @onExit {
+ free(attributes);
+ };
+
+ if (attributes->readonly && attributes->ivar == NULL) return;
+
+ NSString *key = @(property_getName(property));
+ [keys addObject:key];
+ }];
+
+ // It doesn't really matter if we replace another thread's work, since we do
+ // it atomically and the result should be the same.
+ objc_setAssociatedObject(self, MTLModelCachedPropertyKeysKey, keys, OBJC_ASSOCIATION_COPY);
+
+ return keys;
+}
+
+- (NSDictionary *)dictionaryValue {
+ return [self dictionaryWithValuesForKeys:self.class.propertyKeys.allObjects];
+}
+
+#pragma mark Merging
+
+- (void)mergeValueForKey:(NSString *)key fromModel:(MTLModel *)model {
+ NSParameterAssert(key != nil);
+
+ SEL selector = MTLSelectorWithCapitalizedKeyPattern("merge", key, "FromModel:");
+ if (![self respondsToSelector:selector]) {
+ if (model != nil) {
+ [self setValue:[model valueForKey:key] forKey:key];
+ }
+
+ return;
+ }
+
+ NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:[self methodSignatureForSelector:selector]];
+ invocation.target = self;
+ invocation.selector = selector;
+
+ [invocation setArgument:&model atIndex:2];
+ [invocation invoke];
+}
+
+- (void)mergeValuesForKeysFromModel:(MTLModel *)model {
+ NSSet *propertyKeys = model.class.propertyKeys;
+ for (NSString *key in self.class.propertyKeys) {
+ if (![propertyKeys containsObject:key]) continue;
+
+ [self mergeValueForKey:key fromModel:model];
+ }
+}
+
+#pragma mark Validation
+
+- (BOOL)validate:(NSError **)error {
+ for (NSString *key in self.class.propertyKeys) {
+ id value = [self valueForKey:key];
+
+ BOOL success = MTLValidateAndSetValue(self, key, value, NO, error);
+ if (!success) return NO;
+ }
+
+ return YES;
+}
+
+#pragma mark NSCopying
+
+- (instancetype)copyWithZone:(NSZone *)zone {
+ return [[self.class allocWithZone:zone] initWithDictionary:self.dictionaryValue error:NULL];
+}
+
+#pragma mark NSObject
+
+- (NSString *)description {
+ return [NSString stringWithFormat:@"<%@: %p> %@", self.class, self, self.dictionaryValue];
+}
+
+- (NSUInteger)hash {
+ NSUInteger value = 0;
+
+ for (NSString *key in self.class.propertyKeys) {
+ value ^= [[self valueForKey:key] hash];
+ }
+
+ return value;
+}
+
+- (BOOL)isEqual:(MTLModel *)model {
+ if (self == model) return YES;
+ if (![model isMemberOfClass:self.class]) return NO;
+
+ for (NSString *key in self.class.propertyKeys) {
+ id selfValue = [self valueForKey:key];
+ id modelValue = [model valueForKey:key];
+
+ BOOL valuesEqual = ((selfValue == nil && modelValue == nil) || [selfValue isEqual:modelValue]);
+ if (!valuesEqual) return NO;
+ }
+
+ return YES;
+}
+
+@end
diff --git a/Mantle/MTLReflection.h b/Mantle/MTLReflection.h
new file mode 100644
index 0000000..f4c100e
--- /dev/null
+++ b/Mantle/MTLReflection.h
@@ -0,0 +1,31 @@
+//
+// MTLReflection.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-03-12.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+// Creates a selector from a key and a constant string.
+//
+// key - The key to insert into the generated selector. This key should be in
+// its natural case.
+// suffix - A string to append to the key as part of the selector.
+//
+// Returns a selector, or NULL if the input strings cannot form a valid
+// selector.
+SEL MTLSelectorWithKeyPattern(NSString *key, const char *suffix) __attribute__((pure, nonnull(1, 2)));
+
+// Creates a selector from a key and a constant prefix and suffix.
+//
+// prefix - A string to prepend to the key as part of the selector.
+// key - The key to insert into the generated selector. This key should be in
+// its natural case, and will have its first letter capitalized when
+// inserted.
+// suffix - A string to append to the key as part of the selector.
+//
+// Returns a selector, or NULL if the input strings cannot form a valid
+// selector.
+SEL MTLSelectorWithCapitalizedKeyPattern(const char *prefix, NSString *key, const char *suffix) __attribute__((pure, nonnull(1, 2, 3)));
diff --git a/Mantle/MTLReflection.m b/Mantle/MTLReflection.m
new file mode 100644
index 0000000..923e9e2
--- /dev/null
+++ b/Mantle/MTLReflection.m
@@ -0,0 +1,50 @@
+//
+// MTLReflection.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-03-12.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import "MTLReflection.h"
+#import <objc/runtime.h>
+
+SEL MTLSelectorWithKeyPattern(NSString *key, const char *suffix) {
+ NSUInteger keyLength = [key maximumLengthOfBytesUsingEncoding:NSUTF8StringEncoding];
+ NSUInteger suffixLength = strlen(suffix);
+
+ char selector[keyLength + suffixLength + 1];
+
+ BOOL success = [key getBytes:selector maxLength:keyLength usedLength:&keyLength encoding:NSUTF8StringEncoding options:0 range:NSMakeRange(0, key.length) remainingRange:NULL];
+ if (!success) return NULL;
+
+ memcpy(selector + keyLength, suffix, suffixLength);
+ selector[keyLength + suffixLength] = '\0';
+
+ return sel_registerName(selector);
+}
+
+SEL MTLSelectorWithCapitalizedKeyPattern(const char *prefix, NSString *key, const char *suffix) {
+ NSUInteger prefixLength = strlen(prefix);
+ NSUInteger suffixLength = strlen(suffix);
+
+ NSString *initial = [key substringToIndex:1].uppercaseString;
+ NSUInteger initialLength = [initial maximumLengthOfBytesUsingEncoding:NSUTF8StringEncoding];
+
+ NSString *rest = [key substringFromIndex:1];
+ NSUInteger restLength = [rest maximumLengthOfBytesUsingEncoding:NSUTF8StringEncoding];
+
+ char selector[prefixLength + initialLength + restLength + suffixLength + 1];
+ memcpy(selector, prefix, prefixLength);
+
+ BOOL success = [initial getBytes:selector + prefixLength maxLength:initialLength usedLength:&initialLength encoding:NSUTF8StringEncoding options:0 range:NSMakeRange(0, initial.length) remainingRange:NULL];
+ if (!success) return NULL;
+
+ success = [rest getBytes:selector + prefixLength + initialLength maxLength:restLength usedLength:&restLength encoding:NSUTF8StringEncoding options:0 range:NSMakeRange(0, rest.length) remainingRange:NULL];
+ if (!success) return NULL;
+
+ memcpy(selector + prefixLength + initialLength + restLength, suffix, suffixLength);
+ selector[prefixLength + initialLength + restLength + suffixLength] = '\0';
+
+ return sel_registerName(selector);
+}
diff --git a/Mantle/MTLValueTransformer.h b/Mantle/MTLValueTransformer.h
new file mode 100644
index 0000000..231b59f
--- /dev/null
+++ b/Mantle/MTLValueTransformer.h
@@ -0,0 +1,29 @@
+//
+// MTLValueTransformer.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-11.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+typedef id (^MTLValueTransformerBlock)(id);
+
+//
+// A value transformer supporting block-based transformation.
+//
+@interface MTLValueTransformer : NSValueTransformer
+
+// Returns a transformer which transforms values using the given block. Reverse
+// transformations will not be allowed.
++ (instancetype)transformerWithBlock:(MTLValueTransformerBlock)transformationBlock;
+
+// Returns a transformer which transforms values using the given block, for
+// forward or reverse transformations.
++ (instancetype)reversibleTransformerWithBlock:(MTLValueTransformerBlock)transformationBlock;
+
+// Returns a transformer which transforms values using the given blocks.
++ (instancetype)reversibleTransformerWithForwardBlock:(MTLValueTransformerBlock)forwardBlock reverseBlock:(MTLValueTransformerBlock)reverseBlock;
+
+@end
diff --git a/Mantle/MTLValueTransformer.m b/Mantle/MTLValueTransformer.m
new file mode 100644
index 0000000..5400d45
--- /dev/null
+++ b/Mantle/MTLValueTransformer.m
@@ -0,0 +1,88 @@
+//
+// MTLValueTransformer.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-11.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import "MTLValueTransformer.h"
+
+//
+// Any MTLValueTransformer supporting reverse transformation. Necessary because
+// +allowsReverseTransformation is a class method.
+//
+@interface MTLReversibleValueTransformer : MTLValueTransformer
+@end
+
+@interface MTLValueTransformer ()
+
+@property (nonatomic, copy, readonly) MTLValueTransformerBlock forwardBlock;
+@property (nonatomic, copy, readonly) MTLValueTransformerBlock reverseBlock;
+
+@end
+
+@implementation MTLValueTransformer
+
+#pragma mark Lifecycle
+
++ (instancetype)transformerWithBlock:(MTLValueTransformerBlock)transformationBlock {
+ return [[self alloc] initWithForwardBlock:transformationBlock reverseBlock:nil];
+}
+
++ (instancetype)reversibleTransformerWithBlock:(MTLValueTransformerBlock)transformationBlock {
+ return [self reversibleTransformerWithForwardBlock:transformationBlock reverseBlock:transformationBlock];
+}
+
++ (instancetype)reversibleTransformerWithForwardBlock:(MTLValueTransformerBlock)forwardBlock reverseBlock:(MTLValueTransformerBlock)reverseBlock {
+ return [[MTLReversibleValueTransformer alloc] initWithForwardBlock:forwardBlock reverseBlock:reverseBlock];
+}
+
+- (id)initWithForwardBlock:(MTLValueTransformerBlock)forwardBlock reverseBlock:(MTLValueTransformerBlock)reverseBlock {
+ NSParameterAssert(forwardBlock != nil);
+
+ self = [super init];
+ if (self == nil) return nil;
+
+ _forwardBlock = [forwardBlock copy];
+ _reverseBlock = [reverseBlock copy];
+
+ return self;
+}
+
+#pragma mark NSValueTransformer
+
++ (BOOL)allowsReverseTransformation {
+ return NO;
+}
+
++ (Class)transformedValueClass {
+ return [NSObject class];
+}
+
+- (id)transformedValue:(id)value {
+ return self.forwardBlock(value);
+}
+
+@end
+
+@implementation MTLReversibleValueTransformer
+
+#pragma mark Lifecycle
+
+- (id)initWithForwardBlock:(MTLValueTransformerBlock)forwardBlock reverseBlock:(MTLValueTransformerBlock)reverseBlock {
+ NSParameterAssert(reverseBlock != nil);
+ return [super initWithForwardBlock:forwardBlock reverseBlock:reverseBlock];
+}
+
+#pragma mark NSValueTransformer
+
++ (BOOL)allowsReverseTransformation {
+ return YES;
+}
+
+- (id)reverseTransformedValue:(id)value {
+ return self.reverseBlock(value);
+}
+
+@end
diff --git a/Mantle/Mantle.h b/Mantle/Mantle.h
new file mode 100644
index 0000000..86950a0
--- /dev/null
+++ b/Mantle/Mantle.h
@@ -0,0 +1,18 @@
+//
+// Mantle.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-04.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import <Mantle/MTLJSONAdapter.h>
+#import <Mantle/MTLManagedObjectAdapter.h>
+#import <Mantle/MTLModel.h>
+#import <Mantle/MTLModel+NSCoding.h>
+#import <Mantle/MTLValueTransformer.h>
+#import <Mantle/NSArray+MTLManipulationAdditions.h>
+#import <Mantle/NSDictionary+MTLManipulationAdditions.h>
+#import <Mantle/NSObject+MTLComparisonAdditions.h>
+#import <Mantle/NSValueTransformer+MTLInversionAdditions.h>
+#import <Mantle/NSValueTransformer+MTLPredefinedTransformerAdditions.h>
diff --git a/Mantle/NSArray+MTLManipulationAdditions.h b/Mantle/NSArray+MTLManipulationAdditions.h
new file mode 100644
index 0000000..fd7347c
--- /dev/null
+++ b/Mantle/NSArray+MTLManipulationAdditions.h
@@ -0,0 +1,28 @@
+//
+// NSArray+MTLManipulationAdditions.h
+// Mantle
+//
+// Created by Josh Abernathy on 9/19/12.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+@interface NSArray (MTLManipulationAdditions)
+
+// The first object in the array or nil if the array is empty.
+// Forwards to `firstObject` which has been first declared in iOS7, but works with iOS4/10.6.
+@property (nonatomic, readonly, strong) id mtl_firstObject;
+
+// Returns a new array without all instances of the given object.
+- (NSArray *)mtl_arrayByRemovingObject:(id)object;
+
+// Returns a new array without the first object. If the array is empty, it
+// returns the empty array.
+- (NSArray *)mtl_arrayByRemovingFirstObject;
+
+// Returns a new array without the last object. If the array is empty, it
+// returns the empty array.
+- (NSArray *)mtl_arrayByRemovingLastObject;
+
+@end
diff --git a/Mantle/NSArray+MTLManipulationAdditions.m b/Mantle/NSArray+MTLManipulationAdditions.m
new file mode 100644
index 0000000..e6932c9
--- /dev/null
+++ b/Mantle/NSArray+MTLManipulationAdditions.m
@@ -0,0 +1,42 @@
+//
+// NSArray+MTLManipulationAdditions.m
+// Mantle
+//
+// Created by Josh Abernathy on 9/19/12.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import "NSArray+MTLManipulationAdditions.h"
+
+@interface NSArray (MTLDeclarations)
+
+// This declaration is needed so Mantle can be compiled with SDK 6 / 10.8.
+- (id)firstObject;
+
+@end
+
+@implementation NSArray (MTLManipulationAdditions)
+
+- (id)mtl_firstObject {
+ return self.firstObject;
+}
+
+- (instancetype)mtl_arrayByRemovingObject:(id)object {
+ NSMutableArray *result = [self mutableCopy];
+ [result removeObject:object];
+ return result;
+}
+
+- (instancetype)mtl_arrayByRemovingFirstObject {
+ if (self.count == 0) return self;
+
+ return [self subarrayWithRange:NSMakeRange(1, self.count - 1)];
+}
+
+- (instancetype)mtl_arrayByRemovingLastObject {
+ if (self.count == 0) return self;
+
+ return [self subarrayWithRange:NSMakeRange(0, self.count - 1)];
+}
+
+@end
diff --git a/Mantle/NSDictionary+MTLManipulationAdditions.h b/Mantle/NSDictionary+MTLManipulationAdditions.h
new file mode 100644
index 0000000..83254d3
--- /dev/null
+++ b/Mantle/NSDictionary+MTLManipulationAdditions.h
@@ -0,0 +1,25 @@
+//
+// NSDictionary+MTLManipulationAdditions.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-24.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+@interface NSDictionary (MTLManipulationAdditions)
+
+// Merges the keys and values from the given dictionary into the receiver. If
+// both the receiver and `dictionary` have a given key, the value from
+// `dictionary` is used.
+//
+// Returns a new dictionary containing the entries of the receiver combined with
+// those of `dictionary`.
+- (NSDictionary *)mtl_dictionaryByAddingEntriesFromDictionary:(NSDictionary *)dictionary;
+
+// Creates a new dictionary with all the entries for the given keys removed from
+// the receiver.
+- (NSDictionary *)mtl_dictionaryByRemovingEntriesWithKeys:(NSSet *)keys;
+
+@end
diff --git a/Mantle/NSDictionary+MTLManipulationAdditions.m b/Mantle/NSDictionary+MTLManipulationAdditions.m
new file mode 100644
index 0000000..0ed5746
--- /dev/null
+++ b/Mantle/NSDictionary+MTLManipulationAdditions.m
@@ -0,0 +1,25 @@
+//
+// NSDictionary+MTLManipulationAdditions.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-24.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import "NSDictionary+MTLManipulationAdditions.h"
+
+@implementation NSDictionary (MTLManipulationAdditions)
+
+- (NSDictionary *)mtl_dictionaryByAddingEntriesFromDictionary:(NSDictionary *)dictionary {
+ NSMutableDictionary *result = [self mutableCopy];
+ [result addEntriesFromDictionary:dictionary];
+ return result;
+}
+
+- (NSDictionary *)mtl_dictionaryByRemovingEntriesWithKeys:(NSSet *)keys {
+ NSMutableDictionary *result = [self mutableCopy];
+ [result removeObjectsForKeys:keys.allObjects];
+ return result;
+}
+
+@end
diff --git a/Mantle/NSError+MTLModelException.h b/Mantle/NSError+MTLModelException.h
new file mode 100644
index 0000000..f7c1e9e
--- /dev/null
+++ b/Mantle/NSError+MTLModelException.h
@@ -0,0 +1,23 @@
+//
+// NSError+MTLModelException.h
+// Mantle
+//
+// Created by Robert Böhnke on 7/6/13.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+@interface NSError (MTLModelException)
+
+// Creates a new error for an exception that occured during updating an
+// MTLModel.
+//
+// exception - The exception that was thrown while updating the model.
+// This argument must not be nil.
+//
+// Returns an error that takes its localized description and failure reason
+// from the exception.
++ (instancetype)mtl_modelErrorWithException:(NSException *)exception;
+
+@end
diff --git a/Mantle/NSError+MTLModelException.m b/Mantle/NSError+MTLModelException.m
new file mode 100644
index 0000000..8b71e06
--- /dev/null
+++ b/Mantle/NSError+MTLModelException.m
@@ -0,0 +1,36 @@
+//
+// NSError+MTLModelException.m
+// Mantle
+//
+// Created by Robert Böhnke on 7/6/13.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import "MTLModel.h"
+
+#import "NSError+MTLModelException.h"
+
+// The domain for errors originating from MTLModel.
+static NSString * const MTLModelErrorDomain = @"MTLModelErrorDomain";
+
+// An exception was thrown and caught.
+static const NSInteger MTLModelErrorExceptionThrown = 1;
+
+// Associated with the NSException that was caught.
+static NSString * const MTLModelThrownExceptionErrorKey = @"MTLModelThrownException";
+
+@implementation NSError (MTLModelException)
+
++ (instancetype)mtl_modelErrorWithException:(NSException *)exception {
+ NSParameterAssert(exception != nil);
+
+ NSDictionary *userInfo = @{
+ NSLocalizedDescriptionKey: exception.description,
+ NSLocalizedFailureReasonErrorKey: exception.reason,
+ MTLModelThrownExceptionErrorKey: exception
+ };
+
+ return [NSError errorWithDomain:MTLModelErrorDomain code:MTLModelErrorExceptionThrown userInfo:userInfo];
+}
+
+@end
diff --git a/Mantle/NSObject+MTLComparisonAdditions.h b/Mantle/NSObject+MTLComparisonAdditions.h
new file mode 100644
index 0000000..4f7c03e
--- /dev/null
+++ b/Mantle/NSObject+MTLComparisonAdditions.h
@@ -0,0 +1,15 @@
+//
+// NSObject+MTLComparisonAdditions.h
+// Mantle
+//
+// Created by Josh Vera on 10/26/12.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+// Portions copyright (c) 2011 Bitswift. All rights reserved.
+// See the LICENSE file for more information.
+//
+
+#import <Foundation/Foundation.h>
+
+// Returns whether both objects are identical or equal via -isEqual:
+BOOL MTLEqualObjects(id obj1, id obj2);
diff --git a/Mantle/NSObject+MTLComparisonAdditions.m b/Mantle/NSObject+MTLComparisonAdditions.m
new file mode 100644
index 0000000..3b77b35
--- /dev/null
+++ b/Mantle/NSObject+MTLComparisonAdditions.m
@@ -0,0 +1,16 @@
+//
+// NSObject+MTLComparisonAdditions.m
+// Mantle
+//
+// Created by Josh Vera on 10/26/12.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+// Portions copyright (c) 2011 Bitswift. All rights reserved.
+// See the LICENSE file for more information.
+//
+
+#import "NSObject+MTLComparisonAdditions.h"
+
+BOOL MTLEqualObjects(id obj1, id obj2) {
+ return (obj1 == obj2 || [obj1 isEqual:obj2]);
+}
diff --git a/Mantle/NSValueTransformer+MTLInversionAdditions.h b/Mantle/NSValueTransformer+MTLInversionAdditions.h
new file mode 100644
index 0000000..eefceec
--- /dev/null
+++ b/Mantle/NSValueTransformer+MTLInversionAdditions.h
@@ -0,0 +1,21 @@
+//
+// NSValueTransformer+MTLInversionAdditions.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-05-18.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+@interface NSValueTransformer (MTLInversionAdditions)
+
+// Flips the direction of the receiver's transformation, such that
+// -transformedValue: will become -reverseTransformedValue:, and vice-versa.
+//
+// The receiver must allow reverse transformation.
+//
+// Returns an inverted transformer.
+- (NSValueTransformer *)mtl_invertedTransformer;
+
+@end
diff --git a/Mantle/NSValueTransformer+MTLInversionAdditions.m b/Mantle/NSValueTransformer+MTLInversionAdditions.m
new file mode 100644
index 0000000..71fe4b0
--- /dev/null
+++ b/Mantle/NSValueTransformer+MTLInversionAdditions.m
@@ -0,0 +1,24 @@
+//
+// NSValueTransformer+MTLInversionAdditions.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2013-05-18.
+// Copyright (c) 2013 GitHub. All rights reserved.
+//
+
+#import "NSValueTransformer+MTLInversionAdditions.h"
+#import "MTLValueTransformer.h"
+
+@implementation NSValueTransformer (MTLInversionAdditions)
+
+- (NSValueTransformer *)mtl_invertedTransformer {
+ NSParameterAssert(self.class.allowsReverseTransformation);
+
+ return [MTLValueTransformer reversibleTransformerWithForwardBlock:^(id value) {
+ return [self reverseTransformedValue:value];
+ } reverseBlock:^(id value) {
+ return [self transformedValue:value];
+ }];
+}
+
+@end
diff --git a/Mantle/NSValueTransformer+MTLPredefinedTransformerAdditions.h b/Mantle/NSValueTransformer+MTLPredefinedTransformerAdditions.h
new file mode 100644
index 0000000..78a6b19
--- /dev/null
+++ b/Mantle/NSValueTransformer+MTLPredefinedTransformerAdditions.h
@@ -0,0 +1,84 @@
+//
+// NSValueTransformer+MTLPredefinedTransformerAdditions.h
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-27.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+// The name for a value transformer that converts strings into URLs and back.
+extern NSString * const MTLURLValueTransformerName;
+
+// Ensure an NSNumber is backed by __NSCFBoolean/CFBooleanRef
+//
+// NSJSONSerialization, and likely other serialization libraries, ordinarily
+// serialize NSNumbers as numbers, and thus booleans would be serialized as
+// 0/1. The exception is when the NSNumber is backed by __NSCFBoolean, which,
+// though very much an implementation detail, is detected and serialized as a
+// proper boolean.
+extern NSString * const MTLBooleanValueTransformerName;
+
+@interface NSValueTransformer (MTLPredefinedTransformerAdditions)
+
+// Creates a reversible transformer to convert a JSON dictionary into a MTLModel
+// object, and vice-versa.
+//
+// modelClass - The MTLModel subclass to attempt to parse from the JSON. This
+// class must conform to <MTLJSONSerializing>. This argument must
+// not be nil.
+//
+// Returns a reversible transformer which uses MTLJSONAdapter for transforming
+// values back and forth.
++ (NSValueTransformer *)mtl_JSONDictionaryTransformerWithModelClass:(Class)modelClass;
+
+// Creates a reversible transformer to convert an array of JSON dictionaries
+// into an array of MTLModel objects, and vice-versa.
+//
+// modelClass - The MTLModel subclass to attempt to parse from each JSON
+// dictionary. This class must conform to <MTLJSONSerializing>.
+// This argument must not be nil.
+//
+// Returns a reversible transformer which uses MTLJSONAdapter for transforming
+// array elements back and forth.
++ (NSValueTransformer *)mtl_JSONArrayTransformerWithModelClass:(Class)modelClass;
+
+// A reversible value transformer to transform between the keys and objects of a
+// dictionary.
+//
+// dictionary - The dictionary whose keys and values should be
+// transformed between. This argument must not be nil.
+// defaultValue - The result to fall back to, in case no key matching the
+// input value was found during a forward transformation.
+// reverseDefaultValue - The result to fall back to, in case no value matching
+// the input value was found during a reverse
+// transformation.
+//
+// Can for example be used for transforming between enum values and their string
+// representation.
+//
+// NSValueTransformer *valueTransformer = [NSValueTransformer mtl_valueMappingTransformerWithDictionary:@{
+// @"foo": @(EnumDataTypeFoo),
+// @"bar": @(EnumDataTypeBar),
+// } defaultValue: @(EnumDataTypeUndefined) reverseDefaultValue: @"undefined"];
+//
+// Returns a transformer that will map from keys to values in dictionary
+// for forward transformation, and from values to keys for reverse
+// transformations. If no matching key or value can be found, the respective
+// default value is returned.
++ (NSValueTransformer *)mtl_valueMappingTransformerWithDictionary:(NSDictionary *)dictionary defaultValue:(id)defaultValue reverseDefaultValue:(id)reverseDefaultValue;
+
+// Returns a value transformer created by calling
+// `+mtl_valueMappingTransformerWithDictionary:defaultValue:reverseDefaultValue:`
+// with a default value of `nil` and a reverse default value of `nil`.
++ (NSValueTransformer *)mtl_valueMappingTransformerWithDictionary:(NSDictionary *)dictionary;
+
+@end
+
+@interface NSValueTransformer (UnavailableMTLPredefinedTransformerAdditions)
+
++ (NSValueTransformer *)mtl_externalRepresentationTransformerWithModelClass:(Class)modelClass __attribute__((deprecated("Replaced by +mtl_JSONDictionaryTransformerWithModelClass:")));
++ (NSValueTransformer *)mtl_externalRepresentationArrayTransformerWithModelClass:(Class)modelClass __attribute__((deprecated("Replaced by +mtl_JSONArrayTransformerWithModelClass:")));
+
+@end
diff --git a/Mantle/NSValueTransformer+MTLPredefinedTransformerAdditions.m b/Mantle/NSValueTransformer+MTLPredefinedTransformerAdditions.m
new file mode 100644
index 0000000..85c379d
--- /dev/null
+++ b/Mantle/NSValueTransformer+MTLPredefinedTransformerAdditions.m
@@ -0,0 +1,141 @@
+//
+// NSValueTransformer+MTLPredefinedTransformerAdditions.m
+// Mantle
+//
+// Created by Justin Spahr-Summers on 2012-09-27.
+// Copyright (c) 2012 GitHub. All rights reserved.
+//
+
+#import "NSValueTransformer+MTLPredefinedTransformerAdditions.h"
+#import "MTLJSONAdapter.h"
+#import "MTLModel.h"
+#import "MTLValueTransformer.h"
+
+NSString * const MTLURLValueTransformerName = @"MTLURLValueTransformerName";
+NSString * const MTLBooleanValueTransformerName = @"MTLBooleanValueTransformerName";
+
+@implementation NSValueTransformer (MTLPredefinedTransformerAdditions)
+
+#pragma mark Category Loading
+
++ (void)load {
+ @autoreleasepool {
+ MTLValueTransformer *URLValueTransformer = [MTLValueTransformer
+ reversibleTransformerWithForwardBlock:^ id (NSString *str) {
+ if (![str isKindOfClass:NSString.class]) return nil;
+ return [NSURL URLWithString:str];
+ }
+ reverseBlock:^ id (NSURL *URL) {
+ if (![URL isKindOfClass:NSURL.class]) return nil;
+ return URL.absoluteString;
+ }];
+
+ [NSValueTransformer setValueTransformer:URLValueTransformer forName:MTLURLValueTransformerName];
+
+ MTLValueTransformer *booleanValueTransformer = [MTLValueTransformer
+ reversibleTransformerWithBlock:^ id (NSNumber *boolean) {
+ if (![boolean isKindOfClass:NSNumber.class]) return nil;
+ return (NSNumber *)(boolean.boolValue ? kCFBooleanTrue : kCFBooleanFalse);
+ }];
+
+ [NSValueTransformer setValueTransformer:booleanValueTransformer forName:MTLBooleanValueTransformerName];
+ }
+}
+
+#pragma mark Customizable Transformers
+
++ (NSValueTransformer *)mtl_JSONDictionaryTransformerWithModelClass:(Class)modelClass {
+ NSParameterAssert([modelClass isSubclassOfClass:MTLModel.class]);
+ NSParameterAssert([modelClass conformsToProtocol:@protocol(MTLJSONSerializing)]);
+
+ return [MTLValueTransformer
+ reversibleTransformerWithForwardBlock:^ id (id JSONDictionary) {
+ if (JSONDictionary == nil) return nil;
+
+ NSAssert([JSONDictionary isKindOfClass:NSDictionary.class], @"Expected a dictionary, got: %@", JSONDictionary);
+
+ return [MTLJSONAdapter modelOfClass:modelClass fromJSONDictionary:JSONDictionary error:NULL];
+ }
+ reverseBlock:^ id (id model) {
+ if (model == nil) return nil;
+
+ NSAssert([model isKindOfClass:MTLModel.class], @"Expected a MTLModel object, got %@", model);
+ NSAssert([model conformsToProtocol:@protocol(MTLJSONSerializing)], @"Expected a model object conforming to <MTLJSONSerializing>, got %@", model);
+
+ return [MTLJSONAdapter JSONDictionaryFromModel:model];
+ }];
+}
+
++ (NSValueTransformer *)mtl_JSONArrayTransformerWithModelClass:(Class)modelClass {
+ NSValueTransformer *dictionaryTransformer = [self mtl_JSONDictionaryTransformerWithModelClass:modelClass];
+
+ return [MTLValueTransformer
+ reversibleTransformerWithForwardBlock:^ id (NSArray *dictionaries) {
+ if (dictionaries == nil) return nil;
+
+ NSAssert([dictionaries isKindOfClass:NSArray.class], @"Expected a array of dictionaries, got: %@", dictionaries);
+
+ NSMutableArray *models = [NSMutableArray arrayWithCapacity:dictionaries.count];
+ for (id JSONDictionary in dictionaries) {
+ if (JSONDictionary == NSNull.null) {
+ [models addObject:NSNull.null];
+ continue;
+ }
+
+ NSAssert([JSONDictionary isKindOfClass:NSDictionary.class], @"Expected a dictionary or an NSNull, got: %@", JSONDictionary);
+
+ id model = [dictionaryTransformer transformedValue:JSONDictionary];
+ if (model == nil) continue;
+
+ [models addObject:model];
+ }
+
+ return models;
+ }
+ reverseBlock:^ id (NSArray *models) {
+ if (models == nil) return nil;
+
+ NSAssert([models isKindOfClass:NSArray.class], @"Expected a array of MTLModels, got: %@", models);
+
+ NSMutableArray *dictionaries = [NSMutableArray arrayWithCapacity:models.count];
+ for (id model in models) {
+ if (model == NSNull.null) {
+ [dictionaries addObject:NSNull.null];
+ continue;
+ }
+
+ NSAssert([model isKindOfClass:MTLModel.class], @"Expected an MTLModel or an NSNull, got: %@", model);
+
+ NSDictionary *dict = [dictionaryTransformer reverseTransformedValue:model];
+ if (dict == nil) continue;
+
+ [dictionaries addObject:dict];
+ }
+
+ return dictionaries;
+ }];
+}
+
++ (NSValueTransformer *)mtl_valueMappingTransformerWithDictionary:(NSDictionary *)dictionary {
+ return [self mtl_valueMappingTransformerWithDictionary:dictionary defaultValue:nil reverseDefaultValue:nil];
+}
+
++ (NSValueTransformer *)mtl_valueMappingTransformerWithDictionary:(NSDictionary *)dictionary defaultValue:(id)defaultValue reverseDefaultValue:(id)reverseDefaultValue {
+ NSParameterAssert(dictionary != nil);
+ NSParameterAssert(dictionary.count == [[NSSet setWithArray:dictionary.allValues] count]);
+
+ return [MTLValueTransformer reversibleTransformerWithForwardBlock:^(id<NSCopying> key) {
+ return dictionary[key ?: NSNull.null] ?: defaultValue;
+ } reverseBlock:^(id object) {
+ __block id result = nil;
+ [dictionary enumerateKeysAndObjectsUsingBlock:^(id key, id anObject, BOOL *stop) {
+ if ([object isEqual:anObject]) {
+ result = key;
+ *stop = YES;
+ }
+ }];
+ return result ?: reverseDefaultValue;
+ }];
+}
+
+@end
diff --git a/Mantle/extobjc/EXTKeyPathCoding.h b/Mantle/extobjc/EXTKeyPathCoding.h
new file mode 100644
index 0000000..f34dc4a
--- /dev/null
+++ b/Mantle/extobjc/EXTKeyPathCoding.h
@@ -0,0 +1,68 @@
+//
+// EXTKeyPathCoding.h
+// extobjc
+//
+// Created by Justin Spahr-Summers on 19.06.12.
+// Copyright (C) 2012 Justin Spahr-Summers.
+// Released under the MIT license.
+//
+
+#import <Foundation/Foundation.h>
+#import "metamacros.h"
+
+/**
+ * \@keypath allows compile-time verification of key paths. Given a real object
+ * receiver and key path:
+ *
+ * @code
+
+NSString *UTF8StringPath = @keypath(str.lowercaseString.UTF8String);
+// => @"lowercaseString.UTF8String"
+
+NSString *versionPath = @keypath(NSObject, version);
+// => @"version"
+
+NSString *lowercaseStringPath = @keypath(NSString.new, lowercaseString);
+// => @"lowercaseString"
+
+ * @endcode
+ *
+ * ... the macro returns an \c NSString containing all but the first path
+ * component or argument (e.g., @"lowercaseString.UTF8String", @"version").
+ *
+ * In addition to simply creating a key path, this macro ensures that the key
+ * path is valid at compile-time (causing a syntax error if not), and supports
+ * refactoring, such that changing the name of the property will also update any
+ * uses of \@keypath.
+ */
+#define keypath(...) \
+ metamacro_if_eq(1, metamacro_argcount(__VA_ARGS__))(keypath1(__VA_ARGS__))(keypath2(__VA_ARGS__))
+
+#define keypath1(PATH) \
+ (((void)(NO && ((void)PATH, NO)), strchr(# PATH, '.') + 1))
+
+#define keypath2(OBJ, PATH) \
+ (((void)(NO && ((void)OBJ.PATH, NO)), # PATH))
+
+/**
+ * \@collectionKeypath allows compile-time verification of key paths across collections NSArray/NSSet etc. Given a real object
+ * receiver, collection object receiver and related keypaths:
+ *
+ * @code
+
+ NSString *employessFirstNamePath = @collectionKeypath(department.employees, Employee.new, firstName)
+ // => @"employees.firstName"
+
+ NSString *employessFirstNamePath = @collectionKeypath(Department.new, employees, Employee.new, firstName)
+ // => @"employees.firstName"
+
+ * @endcode
+ *
+ */
+#define collectionKeypath(...) \
+ metamacro_if_eq(3, metamacro_argcount(__VA_ARGS__))(collectionKeypath3(__VA_ARGS__))(collectionKeypath4(__VA_ARGS__))
+
+#define collectionKeypath3(PATH, COLLECTION_OBJECT, COLLECTION_PATH) ([[NSString stringWithFormat:@"%s.%s",keypath(PATH), keypath(COLLECTION_OBJECT, COLLECTION_PATH)] UTF8String])
+
+#define collectionKeypath4(OBJ, PATH, COLLECTION_OBJECT, COLLECTION_PATH) ([[NSString stringWithFormat:@"%s.%s",keypath(OBJ, PATH), keypath(COLLECTION_OBJECT, COLLECTION_PATH)] UTF8String])
+
diff --git a/Mantle/extobjc/EXTRuntimeExtensions.h b/Mantle/extobjc/EXTRuntimeExtensions.h
new file mode 100644
index 0000000..191d749
--- /dev/null
+++ b/Mantle/extobjc/EXTRuntimeExtensions.h
@@ -0,0 +1,113 @@
+//
+// EXTRuntimeExtensions.h
+// extobjc
+//
+// Created by Justin Spahr-Summers on 2011-03-05.
+// Copyright (C) 2012 Justin Spahr-Summers.
+// Released under the MIT license.
+//
+
+#import <objc/runtime.h>
+
+/**
+ * Describes the memory management policy of a property.
+ */
+typedef enum {
+ /**
+ * The value is assigned.
+ */
+ mtl_propertyMemoryManagementPolicyAssign = 0,
+
+ /**
+ * The value is retained.
+ */
+ mtl_propertyMemoryManagementPolicyRetain,
+
+ /**
+ * The value is copied.
+ */
+ mtl_propertyMemoryManagementPolicyCopy
+} mtl_propertyMemoryManagementPolicy;
+
+/**
+ * Describes the attributes and type information of a property.
+ */
+typedef struct {
+ /**
+ * Whether this property was declared with the \c readonly attribute.
+ */
+ BOOL readonly;
+
+ /**
+ * Whether this property was declared with the \c nonatomic attribute.
+ */
+ BOOL nonatomic;
+
+ /**
+ * Whether the property is a weak reference.
+ */
+ BOOL weak;
+
+ /**
+ * Whether the property is eligible for garbage collection.
+ */
+ BOOL canBeCollected;
+
+ /**
+ * Whether this property is defined with \c \@dynamic.
+ */
+ BOOL dynamic;
+
+ /**
+ * The memory management policy for this property. This will always be
+ * #mtl_propertyMemoryManagementPolicyAssign if #readonly is \c YES.
+ */
+ mtl_propertyMemoryManagementPolicy memoryManagementPolicy;
+
+ /**
+ * The selector for the getter of this property. This will reflect any
+ * custom \c getter= attribute provided in the property declaration, or the
+ * inferred getter name otherwise.
+ */
+ SEL getter;
+
+ /**
+ * The selector for the setter of this property. This will reflect any
+ * custom \c setter= attribute provided in the property declaration, or the
+ * inferred setter name otherwise.
+ *
+ * @note If #readonly is \c YES, this value will represent what the setter
+ * \e would be, if the property were writable.
+ */
+ SEL setter;
+
+ /**
+ * The backing instance variable for this property, or \c NULL if \c
+ * \c @synthesize was not used, and therefore no instance variable exists. This
+ * would also be the case if the property is implemented dynamically.
+ */
+ const char *ivar;
+
+ /**
+ * If this property is defined as being an instance of a specific class,
+ * this will be the class object representing it.
+ *
+ * This will be \c nil if the property was defined as type \c id, if the
+ * property is not of an object type, or if the class could not be found at
+ * runtime.
+ */
+ Class objectClass;
+
+ /**
+ * The type encoding for the value of this property. This is the type as it
+ * would be returned by the \c \@encode() directive.
+ */
+ char type[];
+} mtl_propertyAttributes;
+
+/**
+ * Returns a pointer to a structure containing information about \a property.
+ * You must \c free() the returned pointer. Returns \c NULL if there is an error
+ * obtaining information from \a property.
+ */
+mtl_propertyAttributes *mtl_copyPropertyAttributes (objc_property_t property);
diff --git a/Mantle/extobjc/EXTRuntimeExtensions.m b/Mantle/extobjc/EXTRuntimeExtensions.m
new file mode 100644
index 0000000..ab1a8bc
--- /dev/null
+++ b/Mantle/extobjc/EXTRuntimeExtensions.m
@@ -0,0 +1,209 @@
+//
+// EXTRuntimeExtensions.m
+// extobjc
+//
+// Created by Justin Spahr-Summers on 2011-03-05.
+// Copyright (C) 2012 Justin Spahr-Summers.
+// Released under the MIT license.
+//
+
+#import "EXTRuntimeExtensions.h"
+
+mtl_propertyAttributes *mtl_copyPropertyAttributes (objc_property_t property) {
+ const char * const attrString = property_getAttributes(property);
+ if (!attrString) {
+ fprintf(stderr, "ERROR: Could not get attribute string from property %s\n", property_getName(property));
+ return NULL;
+ }
+
+ if (attrString[0] != 'T') {
+ fprintf(stderr, "ERROR: Expected attribute string \"%s\" for property %s to start with 'T'\n", attrString, property_getName(property));
+ return NULL;
+ }
+
+ const char *typeString = attrString + 1;
+ const char *next = NSGetSizeAndAlignment(typeString, NULL, NULL);
+ if (!next) {
+ fprintf(stderr, "ERROR: Could not read past type in attribute string \"%s\" for property %s\n", attrString, property_getName(property));
+ return NULL;
+ }
+
+ size_t typeLength = next - typeString;
+ if (!typeLength) {
+ fprintf(stderr, "ERROR: Invalid type in attribute string \"%s\" for property %s\n", attrString, property_getName(property));
+ return NULL;
+ }
+
+ // allocate enough space for the structure and the type string (plus a NUL)
+ mtl_propertyAttributes *attributes = calloc(1, sizeof(mtl_propertyAttributes) + typeLength + 1);
+ if (!attributes) {
+ fprintf(stderr, "ERROR: Could not allocate mtl_propertyAttributes structure for attribute string \"%s\" for property %s\n", attrString, property_getName(property));
+ return NULL;
+ }
+
+ // copy the type string
+ strncpy(attributes->type, typeString, typeLength);
+ attributes->type[typeLength] = '\0';
+
+ // if this is an object type, and immediately followed by a quoted string...
+ if (typeString[0] == *(@encode(id)) && typeString[1] == '"') {
+ // we should be able to extract a class name
+ const char *className = typeString + 2;
+ next = strchr(className, '"');
+
+ if (!next) {
+ fprintf(stderr, "ERROR: Could not read class name in attribute string \"%s\" for property %s\n", attrString, property_getName(property));
+ return NULL;
+ }
+
+ if (className != next) {
+ size_t classNameLength = next - className;
+ char trimmedName[classNameLength + 1];
+
+ strncpy(trimmedName, className, classNameLength);
+ trimmedName[classNameLength] = '\0';
+
+ // attempt to look up the class in the runtime
+ attributes->objectClass = objc_getClass(trimmedName);
+ }
+ }
+
+ if (*next != '\0') {
+ // skip past any junk before the first flag
+ next = strchr(next, ',');
+ }
+
+ while (next && *next == ',') {
+ char flag = next[1];
+ next += 2;
+
+ switch (flag) {
+ case '\0':
+ break;
+
+ case 'R':
+ attributes->readonly = YES;
+ break;
+
+ case 'C':
+ attributes->memoryManagementPolicy = mtl_propertyMemoryManagementPolicyCopy;
+ break;
+
+ case '&':
+ attributes->memoryManagementPolicy = mtl_propertyMemoryManagementPolicyRetain;
+ break;
+
+ case 'N':
+ attributes->nonatomic = YES;
+ break;
+
+ case 'G':
+ case 'S':
+ {
+ const char *nextFlag = strchr(next, ',');
+ SEL name = NULL;
+
+ if (!nextFlag) {
+ // assume that the rest of the string is the selector
+ const char *selectorString = next;
+ next = "";
+
+ name = sel_registerName(selectorString);
+ } else {
+ size_t selectorLength = nextFlag - next;
+ if (!selectorLength) {
+ fprintf(stderr, "ERROR: Found zero length selector name in attribute string \"%s\" for property %s\n", attrString, property_getName(property));
+ goto errorOut;
+ }
+
+ char selectorString[selectorLength + 1];
+
+ strncpy(selectorString, next, selectorLength);
+ selectorString[selectorLength] = '\0';
+
+ name = sel_registerName(selectorString);
+ next = nextFlag;
+ }
+
+ if (flag == 'G')
+ attributes->getter = name;
+ else
+ attributes->setter = name;
+ }
+
+ break;
+
+ case 'D':
+ attributes->dynamic = YES;
+ attributes->ivar = NULL;
+ break;
+
+ case 'V':
+ // assume that the rest of the string (if present) is the ivar name
+ if (*next == '\0') {
+ // if there's nothing there, let's assume this is dynamic
+ attributes->ivar = NULL;
+ } else {
+ attributes->ivar = next;
+ next = "";
+ }
+
+ break;
+
+ case 'W':
+ attributes->weak = YES;
+ break;
+
+ case 'P':
+ attributes->canBeCollected = YES;
+ break;
+
+ case 't':
+ fprintf(stderr, "ERROR: Old-style type encoding is unsupported in attribute string \"%s\" for property %s\n", attrString, property_getName(property));
+
+ // skip over this type encoding
+ while (*next != ',' && *next != '\0')
+ ++next;
+
+ break;
+
+ default:
+ fprintf(stderr, "ERROR: Unrecognized attribute string flag '%c' in attribute string \"%s\" for property %s\n", flag, attrString, property_getName(property));
+ }
+ }
+
+ if (next && *next != '\0') {
+ fprintf(stderr, "Warning: Unparsed data \"%s\" in attribute string \"%s\" for property %s\n", next, attrString, property_getName(property));
+ }
+
+ if (!attributes->getter) {
+ // use the property name as the getter by default
+ attributes->getter = sel_registerName(property_getName(property));
+ }
+
+ if (!attributes->setter) {
+ const char *propertyName = property_getName(property);
+ size_t propertyNameLength = strlen(propertyName);
+
+ // we want to transform the name to setProperty: style
+ size_t setterLength = propertyNameLength + 4;
+
+ char setterName[setterLength + 1];
+ strncpy(setterName, "set", 3);
+ strncpy(setterName + 3, propertyName, propertyNameLength);
+
+ // capitalize property name for the setter
+ setterName[3] = (char)toupper(setterName[3]);
+
+ setterName[setterLength - 1] = ':';
+ setterName[setterLength] = '\0';
+
+ attributes->setter = sel_registerName(setterName);
+ }
+
+ return attributes;
+
+errorOut:
+ free(attributes);
+ return NULL;
+}
diff --git a/Mantle/extobjc/EXTScope.h b/Mantle/extobjc/EXTScope.h
new file mode 100644
index 0000000..7548b81
--- /dev/null
+++ b/Mantle/extobjc/EXTScope.h
@@ -0,0 +1,99 @@
+//
+// EXTScope.h
+// extobjc
+//
+// Created by Justin Spahr-Summers on 2011-05-04.
+// Copyright (C) 2012 Justin Spahr-Summers.
+// Released under the MIT license.
+//
+
+#import "metamacros.h"
+
+/**
+ * \@onExit defines some code to be executed when the current scope exits. The
+ * code must be enclosed in braces and terminated with a semicolon, and will be
+ * executed regardless of how the scope is exited, including from exceptions,
+ * \c goto, \c return, \c break, and \c continue.
+ *
+ * Provided code will go into a block to be executed later. Keep this in mind as
+ * it pertains to memory management, restrictions on assignment, etc. Because
+ * the code is used within a block, \c return is a legal (though perhaps
+ * confusing) way to exit the cleanup block early.
+ *
+ * Multiple \@onExit statements in the same scope are executed in reverse
+ * lexical order. This helps when pairing resource acquisition with \@onExit
+ * statements, as it guarantees teardown in the opposite order of acquisition.
+ *
+ * @note This statement cannot be used within scopes defined without braces
+ * (like a one line \c if). In practice, this is not an issue, since \@onExit is
+ * a useless construct in such a case anyways.
+ */
+#define onExit \
+ try {} @finally {} \
+ __strong mtl_cleanupBlock_t metamacro_concat(mtl_exitBlock_, __LINE__) __attribute__((cleanup(mtl_executeCleanupBlock), unused)) = ^
+
+/**
+ * Creates \c __weak shadow variables for each of the variables provided as
+ * arguments, which can later be made strong again with #strongify.
+ *
+ * This is typically used to weakly reference variables in a block, but then
+ * ensure that the variables stay alive during the actual execution of the block
+ * (if they were live upon entry).
+ *
+ * See #strongify for an example of usage.
+ */
+#define weakify(...) \
+ try {} @finally {} \
+ metamacro_foreach_cxt(mtl_weakify_,, __weak, __VA_ARGS__)
+
+/**
+ * Like #weakify, but uses \c __unsafe_unretained instead, for targets or
+ * classes that do not support weak references.
+ */
+#define unsafeify(...) \
+ try {} @finally {} \
+ metamacro_foreach_cxt(mtl_weakify_,, __unsafe_unretained, __VA_ARGS__)
+
+/**
+ * Strongly references each of the variables provided as arguments, which must
+ * have previously been passed to #weakify.
+ *
+ * The strong references created will shadow the original variable names, such
+ * that the original names can be used without issue (and a significantly
+ * reduced risk of retain cycles) in the current scope.
+ *
+ * @code
+
+ id foo = [[NSObject alloc] init];
+ id bar = [[NSObject alloc] init];
+
+ @weakify(foo, bar);
+
+ // this block will not keep 'foo' or 'bar' alive
+ BOOL (^matchesFooOrBar)(id) = ^ BOOL (id obj){
+ // but now, upon entry, 'foo' and 'bar' will stay alive until the block has
+ // finished executing
+ @strongify(foo, bar);
+
+ return [foo isEqual:obj] || [bar isEqual:obj];
+ };
+
+ * @endcode
+ */
+#define strongify(...) \
+ try {} @finally {} \
+ _Pragma("clang diagnostic push") \
+ _Pragma("clang diagnostic ignored \"-Wshadow\"") \
+ metamacro_foreach(mtl_strongify_,, __VA_ARGS__) \
+ _Pragma("clang diagnostic pop")
+
+/*** implementation details follow ***/
+typedef void (^mtl_cleanupBlock_t)();
+
+void mtl_executeCleanupBlock (__strong mtl_cleanupBlock_t *block);
+
+#define mtl_weakify_(INDEX, CONTEXT, VAR) \
+ CONTEXT __typeof__(VAR) metamacro_concat(VAR, _weak_) = (VAR);
+
+#define mtl_strongify_(INDEX, VAR) \
+ __strong __typeof__(VAR) VAR = metamacro_concat(VAR, _weak_);
diff --git a/Mantle/extobjc/EXTScope.m b/Mantle/extobjc/EXTScope.m
new file mode 100644
index 0000000..b34c1c6
--- /dev/null
+++ b/Mantle/extobjc/EXTScope.m
@@ -0,0 +1,15 @@
+//
+// EXTScope.m
+// extobjc
+//
+// Created by Justin Spahr-Summers on 2011-05-04.
+// Copyright (C) 2012 Justin Spahr-Summers.
+// Released under the MIT license.
+//
+
+#import "EXTScope.h"
+
+void mtl_executeCleanupBlock (__strong mtl_cleanupBlock_t *block) {
+ (*block)();
+}
+
diff --git a/Mantle/extobjc/metamacros.h b/Mantle/extobjc/metamacros.h
new file mode 100644
index 0000000..77a77b5
--- /dev/null
+++ b/Mantle/extobjc/metamacros.h
@@ -0,0 +1,666 @@
+/**
+ * Macros for metaprogramming
+ * ExtendedC
+ *
+ * Copyright (C) 2012 Justin Spahr-Summers
+ * Released under the MIT license
+ */
+
+#ifndef EXTC_METAMACROS_H
+#define EXTC_METAMACROS_H
+
+/**
+ * Executes one or more expressions (which may have a void type, such as a call
+ * to a function that returns no value) and always returns true.
+ */
+#define metamacro_exprify(...) \
+ ((__VA_ARGS__), true)
+
+/**
+ * Returns a string representation of VALUE after full macro expansion.
+ */
+#define metamacro_stringify(VALUE) \
+ metamacro_stringify_(VALUE)
+
+/**
+ * Returns A and B concatenated after full macro expansion.
+ */
+#define metamacro_concat(A, B) \
+ metamacro_concat_(A, B)
+
+/**
+ * Returns the Nth variadic argument (starting from zero). At least
+ * N + 1 variadic arguments must be given. N must be between zero and twenty,
+ * inclusive.
+ */
+#define metamacro_at(N, ...) \
+ metamacro_concat(metamacro_at, N)(__VA_ARGS__)
+
+/**
+ * Returns the number of arguments (up to twenty) provided to the macro. At
+ * least one argument must be provided.
+ *
+ * Inspired by P99: http://p99.gforge.inria.fr
+ */
+#define metamacro_argcount(...) \
+ metamacro_at(20, __VA_ARGS__, 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1)
+
+/**
+ * Identical to #metamacro_foreach_cxt, except that no CONTEXT argument is
+ * given. Only the index and current argument will thus be passed to MACRO.
+ */
+#define metamacro_foreach(MACRO, SEP, ...) \
+ metamacro_foreach_cxt(metamacro_foreach_iter, SEP, MACRO, __VA_ARGS__)
+
+/**
+ * For each consecutive variadic argument (up to twenty), MACRO is passed the
+ * zero-based index of the current argument, CONTEXT, and then the argument
+ * itself. The results of adjoining invocations of MACRO are then separated by
+ * SEP.
+ *
+ * Inspired by P99: http://p99.gforge.inria.fr
+ */
+#define metamacro_foreach_cxt(MACRO, SEP, CONTEXT, ...) \
+ metamacro_concat(metamacro_foreach_cxt, metamacro_argcount(__VA_ARGS__))(MACRO, SEP, CONTEXT, __VA_ARGS__)
+
+/**
+ * Identical to #metamacro_foreach_cxt. This can be used when the former would
+ * fail due to recursive macro expansion.
+ */
+#define metamacro_foreach_cxt_recursive(MACRO, SEP, CONTEXT, ...) \
+ metamacro_concat(metamacro_foreach_cxt_recursive, metamacro_argcount(__VA_ARGS__))(MACRO, SEP, CONTEXT, __VA_ARGS__)
+
+/**
+ * In consecutive order, appends each variadic argument (up to twenty) onto
+ * BASE. The resulting concatenations are then separated by SEP.
+ *
+ * This is primarily useful to manipulate a list of macro invocations into instead
+ * invoking a different, possibly related macro.
+ */
+#define metamacro_foreach_concat(BASE, SEP, ...) \
+ metamacro_foreach_cxt(metamacro_foreach_concat_iter, SEP, BASE, __VA_ARGS__)
+
+/**
+ * Iterates COUNT times, each time invoking MACRO with the current index
+ * (starting at zero) and CONTEXT. The results of adjoining invocations of MACRO
+ * are then separated by SEP.
+ *
+ * COUNT must be an integer between zero and twenty, inclusive.
+ */
+#define metamacro_for_cxt(COUNT, MACRO, SEP, CONTEXT) \
+ metamacro_concat(metamacro_for_cxt, COUNT)(MACRO, SEP, CONTEXT)
+
+/**
+ * Returns the first argument given. At least one argument must be provided.
+ *
+ * This is useful when implementing a variadic macro, where you may have only
+ * one variadic argument, but no way to retrieve it (for example, because \c ...
+ * always needs to match at least one argument).
+ *
+ * @code
+
+#define varmacro(...) \
+ metamacro_head(__VA_ARGS__)
+
+ * @endcode
+ */
+#define metamacro_head(...) \
+ metamacro_head_(__VA_ARGS__, 0)
+
+/**
+ * Returns every argument except the first. At least two arguments must be
+ * provided.
+ */
+#define metamacro_tail(...) \
+ metamacro_tail_(__VA_ARGS__)
+
+/**
+ * Returns the first N (up to twenty) variadic arguments as a new argument list.
+ * At least N variadic arguments must be provided.
+ */
+#define metamacro_take(N, ...) \
+ metamacro_concat(metamacro_take, N)(__VA_ARGS__)
+
+/**
+ * Removes the first N (up to twenty) variadic arguments from the given argument
+ * list. At least N variadic arguments must be provided.
+ */
+#define metamacro_drop(N, ...) \
+ metamacro_concat(metamacro_drop, N)(__VA_ARGS__)
+
+/**
+ * Decrements VAL, which must be a number between zero and twenty, inclusive.
+ *
+ * This is primarily useful when dealing with indexes and counts in
+ * metaprogramming.
+ */
+#define metamacro_dec(VAL) \
+ metamacro_at(VAL, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19)
+
+/**
+ * Increments VAL, which must be a number between zero and twenty, inclusive.
+ *
+ * This is primarily useful when dealing with indexes and counts in
+ * metaprogramming.
+ */
+#define metamacro_inc(VAL) \
+ metamacro_at(VAL, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21)
+
+/**
+ * If A is equal to B, the next argument list is expanded; otherwise, the
+ * argument list after that is expanded. A and B must be numbers between zero
+ * and twenty, inclusive. Additionally, B must be greater than or equal to A.
+ *
+ * @code
+
+// expands to true
+metamacro_if_eq(0, 0)(true)(false)
+
+// expands to false
+metamacro_if_eq(0, 1)(true)(false)
+
+ * @endcode
+ *
+ * This is primarily useful when dealing with indexes and counts in
+ * metaprogramming.
+ */
+#define metamacro_if_eq(A, B) \
+ metamacro_concat(metamacro_if_eq, A)(B)
+
+/**
+ * Identical to #metamacro_if_eq. This can be used when the former would fail
+ * due to recursive macro expansion.
+ */
+#define metamacro_if_eq_recursive(A, B) \
+ metamacro_concat(metamacro_if_eq_recursive, A)(B)
+
+/**
+ * Returns 1 if N is an even number, or 0 otherwise. N must be between zero and
+ * twenty, inclusive.
+ *
+ * For the purposes of this test, zero is considered even.
+ */
+#define metamacro_is_even(N) \
+ metamacro_at(N, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1)
+
+/**
+ * Returns the logical NOT of B, which must be the number zero or one.
+ */
+#define metamacro_not(B) \
+ metamacro_at(B, 1, 0)
+
+// IMPLEMENTATION DETAILS FOLLOW!
+// Do not write code that depends on anything below this line.
+#define metamacro_stringify_(VALUE) # VALUE
+#define metamacro_concat_(A, B) A ## B
+#define metamacro_foreach_iter(INDEX, MACRO, ARG) MACRO(INDEX, ARG)
+#define metamacro_head_(FIRST, ...) FIRST
+#define metamacro_tail_(FIRST, ...) __VA_ARGS__
+#define metamacro_consume_(...)
+#define metamacro_expand_(...) __VA_ARGS__
+
+// implemented from scratch so that metamacro_concat() doesn't end up nesting
+#define metamacro_foreach_concat_iter(INDEX, BASE, ARG) metamacro_foreach_concat_iter_(BASE, ARG)
+#define metamacro_foreach_concat_iter_(BASE, ARG) BASE ## ARG
+
+// metamacro_at expansions
+#define metamacro_at0(...) metamacro_head(__VA_ARGS__)
+#define metamacro_at1(_0, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at2(_0, _1, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at3(_0, _1, _2, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at4(_0, _1, _2, _3, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at5(_0, _1, _2, _3, _4, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at6(_0, _1, _2, _3, _4, _5, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at7(_0, _1, _2, _3, _4, _5, _6, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at8(_0, _1, _2, _3, _4, _5, _6, _7, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at9(_0, _1, _2, _3, _4, _5, _6, _7, _8, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at10(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at11(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at12(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at13(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at14(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at15(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at16(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at17(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at18(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at19(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18, ...) metamacro_head(__VA_ARGS__)
+#define metamacro_at20(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18, _19, ...) metamacro_head(__VA_ARGS__)
+
+// metamacro_foreach_cxt expansions
+#define metamacro_foreach_cxt0(MACRO, SEP, CONTEXT)
+#define metamacro_foreach_cxt1(MACRO, SEP, CONTEXT, _0) MACRO(0, CONTEXT, _0)
+
+#define metamacro_foreach_cxt2(MACRO, SEP, CONTEXT, _0, _1) \
+ metamacro_foreach_cxt1(MACRO, SEP, CONTEXT, _0) \
+ SEP \
+ MACRO(1, CONTEXT, _1)
+
+#define metamacro_foreach_cxt3(MACRO, SEP, CONTEXT, _0, _1, _2) \
+ metamacro_foreach_cxt2(MACRO, SEP, CONTEXT, _0, _1) \
+ SEP \
+ MACRO(2, CONTEXT, _2)
+
+#define metamacro_foreach_cxt4(MACRO, SEP, CONTEXT, _0, _1, _2, _3) \
+ metamacro_foreach_cxt3(MACRO, SEP, CONTEXT, _0, _1, _2) \
+ SEP \
+ MACRO(3, CONTEXT, _3)
+
+#define metamacro_foreach_cxt5(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4) \
+ metamacro_foreach_cxt4(MACRO, SEP, CONTEXT, _0, _1, _2, _3) \
+ SEP \
+ MACRO(4, CONTEXT, _4)
+
+#define metamacro_foreach_cxt6(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5) \
+ metamacro_foreach_cxt5(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4) \
+ SEP \
+ MACRO(5, CONTEXT, _5)
+
+#define metamacro_foreach_cxt7(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6) \
+ metamacro_foreach_cxt6(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5) \
+ SEP \
+ MACRO(6, CONTEXT, _6)
+
+#define metamacro_foreach_cxt8(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7) \
+ metamacro_foreach_cxt7(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6) \
+ SEP \
+ MACRO(7, CONTEXT, _7)
+
+#define metamacro_foreach_cxt9(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8) \
+ metamacro_foreach_cxt8(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7) \
+ SEP \
+ MACRO(8, CONTEXT, _8)
+
+#define metamacro_foreach_cxt10(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9) \
+ metamacro_foreach_cxt9(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8) \
+ SEP \
+ MACRO(9, CONTEXT, _9)
+
+#define metamacro_foreach_cxt11(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10) \
+ metamacro_foreach_cxt10(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9) \
+ SEP \
+ MACRO(10, CONTEXT, _10)
+
+#define metamacro_foreach_cxt12(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11) \
+ metamacro_foreach_cxt11(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10) \
+ SEP \
+ MACRO(11, CONTEXT, _11)
+
+#define metamacro_foreach_cxt13(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12) \
+ metamacro_foreach_cxt12(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11) \
+ SEP \
+ MACRO(12, CONTEXT, _12)
+
+#define metamacro_foreach_cxt14(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13) \
+ metamacro_foreach_cxt13(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12) \
+ SEP \
+ MACRO(13, CONTEXT, _13)
+
+#define metamacro_foreach_cxt15(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14) \
+ metamacro_foreach_cxt14(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13) \
+ SEP \
+ MACRO(14, CONTEXT, _14)
+
+#define metamacro_foreach_cxt16(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15) \
+ metamacro_foreach_cxt15(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14) \
+ SEP \
+ MACRO(15, CONTEXT, _15)
+
+#define metamacro_foreach_cxt17(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16) \
+ metamacro_foreach_cxt16(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15) \
+ SEP \
+ MACRO(16, CONTEXT, _16)
+
+#define metamacro_foreach_cxt18(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17) \
+ metamacro_foreach_cxt17(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16) \
+ SEP \
+ MACRO(17, CONTEXT, _17)
+
+#define metamacro_foreach_cxt19(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18) \
+ metamacro_foreach_cxt18(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17) \
+ SEP \
+ MACRO(18, CONTEXT, _18)
+
+#define metamacro_foreach_cxt20(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18, _19) \
+ metamacro_foreach_cxt19(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18) \
+ SEP \
+ MACRO(19, CONTEXT, _19)
+
+// metamacro_foreach_cxt_recursive expansions
+#define metamacro_foreach_cxt_recursive0(MACRO, SEP, CONTEXT)
+#define metamacro_foreach_cxt_recursive1(MACRO, SEP, CONTEXT, _0) MACRO(0, CONTEXT, _0)
+
+#define metamacro_foreach_cxt_recursive2(MACRO, SEP, CONTEXT, _0, _1) \
+ metamacro_foreach_cxt_recursive1(MACRO, SEP, CONTEXT, _0) \
+ SEP \
+ MACRO(1, CONTEXT, _1)
+
+#define metamacro_foreach_cxt_recursive3(MACRO, SEP, CONTEXT, _0, _1, _2) \
+ metamacro_foreach_cxt_recursive2(MACRO, SEP, CONTEXT, _0, _1) \
+ SEP \
+ MACRO(2, CONTEXT, _2)
+
+#define metamacro_foreach_cxt_recursive4(MACRO, SEP, CONTEXT, _0, _1, _2, _3) \
+ metamacro_foreach_cxt_recursive3(MACRO, SEP, CONTEXT, _0, _1, _2) \
+ SEP \
+ MACRO(3, CONTEXT, _3)
+
+#define metamacro_foreach_cxt_recursive5(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4) \
+ metamacro_foreach_cxt_recursive4(MACRO, SEP, CONTEXT, _0, _1, _2, _3) \
+ SEP \
+ MACRO(4, CONTEXT, _4)
+
+#define metamacro_foreach_cxt_recursive6(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5) \
+ metamacro_foreach_cxt_recursive5(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4) \
+ SEP \
+ MACRO(5, CONTEXT, _5)
+
+#define metamacro_foreach_cxt_recursive7(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6) \
+ metamacro_foreach_cxt_recursive6(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5) \
+ SEP \
+ MACRO(6, CONTEXT, _6)
+
+#define metamacro_foreach_cxt_recursive8(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7) \
+ metamacro_foreach_cxt_recursive7(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6) \
+ SEP \
+ MACRO(7, CONTEXT, _7)
+
+#define metamacro_foreach_cxt_recursive9(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8) \
+ metamacro_foreach_cxt_recursive8(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7) \
+ SEP \
+ MACRO(8, CONTEXT, _8)
+
+#define metamacro_foreach_cxt_recursive10(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9) \
+ metamacro_foreach_cxt_recursive9(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8) \
+ SEP \
+ MACRO(9, CONTEXT, _9)
+
+#define metamacro_foreach_cxt_recursive11(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10) \
+ metamacro_foreach_cxt_recursive10(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9) \
+ SEP \
+ MACRO(10, CONTEXT, _10)
+
+#define metamacro_foreach_cxt_recursive12(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11) \
+ metamacro_foreach_cxt_recursive11(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10) \
+ SEP \
+ MACRO(11, CONTEXT, _11)
+
+#define metamacro_foreach_cxt_recursive13(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12) \
+ metamacro_foreach_cxt_recursive12(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11) \
+ SEP \
+ MACRO(12, CONTEXT, _12)
+
+#define metamacro_foreach_cxt_recursive14(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13) \
+ metamacro_foreach_cxt_recursive13(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12) \
+ SEP \
+ MACRO(13, CONTEXT, _13)
+
+#define metamacro_foreach_cxt_recursive15(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14) \
+ metamacro_foreach_cxt_recursive14(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13) \
+ SEP \
+ MACRO(14, CONTEXT, _14)
+
+#define metamacro_foreach_cxt_recursive16(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15) \
+ metamacro_foreach_cxt_recursive15(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14) \
+ SEP \
+ MACRO(15, CONTEXT, _15)
+
+#define metamacro_foreach_cxt_recursive17(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16) \
+ metamacro_foreach_cxt_recursive16(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15) \
+ SEP \
+ MACRO(16, CONTEXT, _16)
+
+#define metamacro_foreach_cxt_recursive18(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17) \
+ metamacro_foreach_cxt_recursive17(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16) \
+ SEP \
+ MACRO(17, CONTEXT, _17)
+
+#define metamacro_foreach_cxt_recursive19(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18) \
+ metamacro_foreach_cxt_recursive18(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17) \
+ SEP \
+ MACRO(18, CONTEXT, _18)
+
+#define metamacro_foreach_cxt_recursive20(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18, _19) \
+ metamacro_foreach_cxt_recursive19(MACRO, SEP, CONTEXT, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18) \
+ SEP \
+ MACRO(19, CONTEXT, _19)
+
+// metamacro_for_cxt expansions
+#define metamacro_for_cxt0(MACRO, SEP, CONTEXT)
+#define metamacro_for_cxt1(MACRO, SEP, CONTEXT) MACRO(0, CONTEXT)
+
+#define metamacro_for_cxt2(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt1(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(1, CONTEXT)
+
+#define metamacro_for_cxt3(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt2(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(2, CONTEXT)
+
+#define metamacro_for_cxt4(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt3(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(3, CONTEXT)
+
+#define metamacro_for_cxt5(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt4(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(4, CONTEXT)
+
+#define metamacro_for_cxt6(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt5(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(5, CONTEXT)
+
+#define metamacro_for_cxt7(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt6(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(6, CONTEXT)
+
+#define metamacro_for_cxt8(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt7(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(7, CONTEXT)
+
+#define metamacro_for_cxt9(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt8(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(8, CONTEXT)
+
+#define metamacro_for_cxt10(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt9(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(9, CONTEXT)
+
+#define metamacro_for_cxt11(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt10(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(10, CONTEXT)
+
+#define metamacro_for_cxt12(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt11(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(11, CONTEXT)
+
+#define metamacro_for_cxt13(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt12(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(12, CONTEXT)
+
+#define metamacro_for_cxt14(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt13(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(13, CONTEXT)
+
+#define metamacro_for_cxt15(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt14(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(14, CONTEXT)
+
+#define metamacro_for_cxt16(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt15(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(15, CONTEXT)
+
+#define metamacro_for_cxt17(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt16(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(16, CONTEXT)
+
+#define metamacro_for_cxt18(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt17(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(17, CONTEXT)
+
+#define metamacro_for_cxt19(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt18(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(18, CONTEXT)
+
+#define metamacro_for_cxt20(MACRO, SEP, CONTEXT) \
+ metamacro_for_cxt19(MACRO, SEP, CONTEXT) \
+ SEP \
+ MACRO(19, CONTEXT)
+
+// metamacro_if_eq expansions
+#define metamacro_if_eq0(VALUE) \
+ metamacro_concat(metamacro_if_eq0_, VALUE)
+
+#define metamacro_if_eq0_0(...) __VA_ARGS__ metamacro_consume_
+#define metamacro_if_eq0_1(...) metamacro_expand_
+#define metamacro_if_eq0_2(...) metamacro_expand_
+#define metamacro_if_eq0_3(...) metamacro_expand_
+#define metamacro_if_eq0_4(...) metamacro_expand_
+#define metamacro_if_eq0_5(...) metamacro_expand_
+#define metamacro_if_eq0_6(...) metamacro_expand_
+#define metamacro_if_eq0_7(...) metamacro_expand_
+#define metamacro_if_eq0_8(...) metamacro_expand_
+#define metamacro_if_eq0_9(...) metamacro_expand_
+#define metamacro_if_eq0_10(...) metamacro_expand_
+#define metamacro_if_eq0_11(...) metamacro_expand_
+#define metamacro_if_eq0_12(...) metamacro_expand_
+#define metamacro_if_eq0_13(...) metamacro_expand_
+#define metamacro_if_eq0_14(...) metamacro_expand_
+#define metamacro_if_eq0_15(...) metamacro_expand_
+#define metamacro_if_eq0_16(...) metamacro_expand_
+#define metamacro_if_eq0_17(...) metamacro_expand_
+#define metamacro_if_eq0_18(...) metamacro_expand_
+#define metamacro_if_eq0_19(...) metamacro_expand_
+#define metamacro_if_eq0_20(...) metamacro_expand_
+
+#define metamacro_if_eq1(VALUE) metamacro_if_eq0(metamacro_dec(VALUE))
+#define metamacro_if_eq2(VALUE) metamacro_if_eq1(metamacro_dec(VALUE))
+#define metamacro_if_eq3(VALUE) metamacro_if_eq2(metamacro_dec(VALUE))
+#define metamacro_if_eq4(VALUE) metamacro_if_eq3(metamacro_dec(VALUE))
+#define metamacro_if_eq5(VALUE) metamacro_if_eq4(metamacro_dec(VALUE))
+#define metamacro_if_eq6(VALUE) metamacro_if_eq5(metamacro_dec(VALUE))
+#define metamacro_if_eq7(VALUE) metamacro_if_eq6(metamacro_dec(VALUE))
+#define metamacro_if_eq8(VALUE) metamacro_if_eq7(metamacro_dec(VALUE))
+#define metamacro_if_eq9(VALUE) metamacro_if_eq8(metamacro_dec(VALUE))
+#define metamacro_if_eq10(VALUE) metamacro_if_eq9(metamacro_dec(VALUE))
+#define metamacro_if_eq11(VALUE) metamacro_if_eq10(metamacro_dec(VALUE))
+#define metamacro_if_eq12(VALUE) metamacro_if_eq11(metamacro_dec(VALUE))
+#define metamacro_if_eq13(VALUE) metamacro_if_eq12(metamacro_dec(VALUE))
+#define metamacro_if_eq14(VALUE) metamacro_if_eq13(metamacro_dec(VALUE))
+#define metamacro_if_eq15(VALUE) metamacro_if_eq14(metamacro_dec(VALUE))
+#define metamacro_if_eq16(VALUE) metamacro_if_eq15(metamacro_dec(VALUE))
+#define metamacro_if_eq17(VALUE) metamacro_if_eq16(metamacro_dec(VALUE))
+#define metamacro_if_eq18(VALUE) metamacro_if_eq17(metamacro_dec(VALUE))
+#define metamacro_if_eq19(VALUE) metamacro_if_eq18(metamacro_dec(VALUE))
+#define metamacro_if_eq20(VALUE) metamacro_if_eq19(metamacro_dec(VALUE))
+
+// metamacro_if_eq_recursive expansions
+#define metamacro_if_eq_recursive0(VALUE) \
+ metamacro_concat(metamacro_if_eq_recursive0_, VALUE)
+
+#define metamacro_if_eq_recursive0_0(...) __VA_ARGS__ metamacro_consume_
+#define metamacro_if_eq_recursive0_1(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_2(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_3(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_4(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_5(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_6(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_7(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_8(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_9(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_10(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_11(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_12(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_13(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_14(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_15(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_16(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_17(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_18(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_19(...) metamacro_expand_
+#define metamacro_if_eq_recursive0_20(...) metamacro_expand_
+
+#define metamacro_if_eq_recursive1(VALUE) metamacro_if_eq_recursive0(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive2(VALUE) metamacro_if_eq_recursive1(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive3(VALUE) metamacro_if_eq_recursive2(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive4(VALUE) metamacro_if_eq_recursive3(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive5(VALUE) metamacro_if_eq_recursive4(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive6(VALUE) metamacro_if_eq_recursive5(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive7(VALUE) metamacro_if_eq_recursive6(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive8(VALUE) metamacro_if_eq_recursive7(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive9(VALUE) metamacro_if_eq_recursive8(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive10(VALUE) metamacro_if_eq_recursive9(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive11(VALUE) metamacro_if_eq_recursive10(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive12(VALUE) metamacro_if_eq_recursive11(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive13(VALUE) metamacro_if_eq_recursive12(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive14(VALUE) metamacro_if_eq_recursive13(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive15(VALUE) metamacro_if_eq_recursive14(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive16(VALUE) metamacro_if_eq_recursive15(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive17(VALUE) metamacro_if_eq_recursive16(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive18(VALUE) metamacro_if_eq_recursive17(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive19(VALUE) metamacro_if_eq_recursive18(metamacro_dec(VALUE))
+#define metamacro_if_eq_recursive20(VALUE) metamacro_if_eq_recursive19(metamacro_dec(VALUE))
+
+// metamacro_take expansions
+#define metamacro_take0(...)
+#define metamacro_take1(...) metamacro_head(__VA_ARGS__)
+#define metamacro_take2(...) metamacro_head(__VA_ARGS__), metamacro_take1(metamacro_tail(__VA_ARGS__))
+#define metamacro_take3(...) metamacro_head(__VA_ARGS__), metamacro_take2(metamacro_tail(__VA_ARGS__))
+#define metamacro_take4(...) metamacro_head(__VA_ARGS__), metamacro_take3(metamacro_tail(__VA_ARGS__))
+#define metamacro_take5(...) metamacro_head(__VA_ARGS__), metamacro_take4(metamacro_tail(__VA_ARGS__))
+#define metamacro_take6(...) metamacro_head(__VA_ARGS__), metamacro_take5(metamacro_tail(__VA_ARGS__))
+#define metamacro_take7(...) metamacro_head(__VA_ARGS__), metamacro_take6(metamacro_tail(__VA_ARGS__))
+#define metamacro_take8(...) metamacro_head(__VA_ARGS__), metamacro_take7(metamacro_tail(__VA_ARGS__))
+#define metamacro_take9(...) metamacro_head(__VA_ARGS__), metamacro_take8(metamacro_tail(__VA_ARGS__))
+#define metamacro_take10(...) metamacro_head(__VA_ARGS__), metamacro_take9(metamacro_tail(__VA_ARGS__))
+#define metamacro_take11(...) metamacro_head(__VA_ARGS__), metamacro_take10(metamacro_tail(__VA_ARGS__))
+#define metamacro_take12(...) metamacro_head(__VA_ARGS__), metamacro_take11(metamacro_tail(__VA_ARGS__))
+#define metamacro_take13(...) metamacro_head(__VA_ARGS__), metamacro_take12(metamacro_tail(__VA_ARGS__))
+#define metamacro_take14(...) metamacro_head(__VA_ARGS__), metamacro_take13(metamacro_tail(__VA_ARGS__))
+#define metamacro_take15(...) metamacro_head(__VA_ARGS__), metamacro_take14(metamacro_tail(__VA_ARGS__))
+#define metamacro_take16(...) metamacro_head(__VA_ARGS__), metamacro_take15(metamacro_tail(__VA_ARGS__))
+#define metamacro_take17(...) metamacro_head(__VA_ARGS__), metamacro_take16(metamacro_tail(__VA_ARGS__))
+#define metamacro_take18(...) metamacro_head(__VA_ARGS__), metamacro_take17(metamacro_tail(__VA_ARGS__))
+#define metamacro_take19(...) metamacro_head(__VA_ARGS__), metamacro_take18(metamacro_tail(__VA_ARGS__))
+#define metamacro_take20(...) metamacro_head(__VA_ARGS__), metamacro_take19(metamacro_tail(__VA_ARGS__))
+
+// metamacro_drop expansions
+#define metamacro_drop0(...) __VA_ARGS__
+#define metamacro_drop1(...) metamacro_tail(__VA_ARGS__)
+#define metamacro_drop2(...) metamacro_drop1(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop3(...) metamacro_drop2(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop4(...) metamacro_drop3(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop5(...) metamacro_drop4(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop6(...) metamacro_drop5(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop7(...) metamacro_drop6(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop8(...) metamacro_drop7(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop9(...) metamacro_drop8(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop10(...) metamacro_drop9(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop11(...) metamacro_drop10(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop12(...) metamacro_drop11(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop13(...) metamacro_drop12(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop14(...) metamacro_drop13(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop15(...) metamacro_drop14(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop16(...) metamacro_drop15(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop17(...) metamacro_drop16(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop18(...) metamacro_drop17(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop19(...) metamacro_drop18(metamacro_tail(__VA_ARGS__))
+#define metamacro_drop20(...) metamacro_drop19(metamacro_tail(__VA_ARGS__))
+
+#endif
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cfe58f1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,481 @@
+# Mantle
+
+Mantle makes it easy to write a simple model layer for your Cocoa or Cocoa Touch
+application.
+
+## The Typical Model Object
+
+What's wrong with the way model objects are usually written in Objective-C?
+
+Let's use the [GitHub API](http://developer.github.com) for demonstration. How
+would one typically represent a [GitHub
+issue](http://developer.github.com/v3/issues/#get-a-single-issue) in
+Objective-C?
+
+```objc
+typedef enum : NSUInteger {
+ GHIssueStateOpen,
+ GHIssueStateClosed
+} GHIssueState;
+
+@interface GHIssue : NSObject <NSCoding, NSCopying>
+
+@property (nonatomic, copy, readonly) NSURL *URL;
+@property (nonatomic, copy, readonly) NSURL *HTMLURL;
+@property (nonatomic, copy, readonly) NSNumber *number;
+@property (nonatomic, assign, readonly) GHIssueState state;
+@property (nonatomic, copy, readonly) NSString *reporterLogin;
+@property (nonatomic, copy, readonly) NSDate *updatedAt;
+@property (nonatomic, strong, readonly) GHUser *assignee;
+
+@property (nonatomic, copy) NSString *title;
+@property (nonatomic, copy) NSString *body;
+
+- (id)initWithDictionary:(NSDictionary *)dictionary;
+
+@end
+```
+
+```objc
+@implementation GHIssue
+
++ (NSDateFormatter *)dateFormatter {
+ NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
+ dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US_POSIX"];
+ dateFormatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ss'Z'";
+ return dateFormatter;
+}
+
+- (id)initWithDictionary:(NSDictionary *)dictionary {
+ self = [self init];
+ if (self == nil) return nil;
+
+ _URL = [NSURL URLWithString:dictionary[@"url"]];
+ _HTMLURL = [NSURL URLWithString:dictionary[@"html_url"]];
+ _number = dictionary[@"number"];
+
+ if ([dictionary[@"state"] isEqualToString:@"open"]) {
+ _state = GHIssueStateOpen;
+ } else if ([dictionary[@"state"] isEqualToString:@"closed"]) {
+ _state = GHIssueStateClosed;
+ }
+
+ _title = [dictionary[@"title"] copy];
+ _body = [dictionary[@"body"] copy];
+ _reporterLogin = [dictionary[@"user"][@"login"] copy];
+ _assignee = [[GHUser alloc] initWithDictionary:dictionary[@"assignee"]];
+
+ _updatedAt = [self.class.dateFormatter dateFromString:dictionary[@"updated_at"]];
+
+ return self;
+}
+
+- (id)initWithCoder:(NSCoder *)coder {
+ self = [self init];
+ if (self == nil) return nil;
+
+ _URL = [coder decodeObjectForKey:@"URL"];
+ _HTMLURL = [coder decodeObjectForKey:@"HTMLURL"];
+ _number = [coder decodeObjectForKey:@"number"];
+ _state = [coder decodeUnsignedIntegerForKey:@"state"];
+ _title = [coder decodeObjectForKey:@"title"];
+ _body = [coder decodeObjectForKey:@"body"];
+ _reporterLogin = [coder decodeObjectForKey:@"reporterLogin"];
+ _assignee = [coder decodeObjectForKey:@"assignee"];
+ _updatedAt = [coder decodeObjectForKey:@"updatedAt"];
+
+ return self;
+}
+
+- (void)encodeWithCoder:(NSCoder *)coder {
+ if (self.URL != nil) [coder encodeObject:self.URL forKey:@"URL"];
+ if (self.HTMLURL != nil) [coder encodeObject:self.HTMLURL forKey:@"HTMLURL"];
+ if (self.number != nil) [coder encodeObject:self.number forKey:@"number"];
+ if (self.title != nil) [coder encodeObject:self.title forKey:@"title"];
+ if (self.body != nil) [coder encodeObject:self.body forKey:@"body"];
+ if (self.reporterLogin != nil) [coder encodeObject:self.reporterLogin forKey:@"reporterLogin"];
+ if (self.assignee != nil) [coder encodeObject:self.assignee forKey:@"assignee"];
+ if (self.updatedAt != nil) [coder encodeObject:self.updatedAt forKey:@"updatedAt"];
+
+ [coder encodeUnsignedInteger:self.state forKey:@"state"];
+}
+
+- (id)copyWithZone:(NSZone *)zone {
+ GHIssue *issue = [[self.class allocWithZone:zone] init];
+ issue->_URL = self.URL;
+ issue->_HTMLURL = self.HTMLURL;
+ issue->_number = self.number;
+ issue->_state = self.state;
+ issue->_reporterLogin = self.reporterLogin;
+ issue->_assignee = self.assignee;
+ issue->_updatedAt = self.updatedAt;
+
+ issue.title = self.title;
+ issue.body = self.body;
+}
+
+- (NSUInteger)hash {
+ return self.number.hash;
+}
+
+- (BOOL)isEqual:(GHIssue *)issue {
+ if (![issue isKindOfClass:GHIssue.class]) return NO;
+
+ return [self.number isEqual:issue.number] && [self.title isEqual:issue.title] && [self.body isEqual:issue.body];
+}
+
+@end
+```
+
+Whew, that's a lot of boilerplate for something so simple! And, even then, there
+are some problems that this example doesn't address:
+
+ * If the `url` or `html_url` field is missing, `+[NSURL URLWithString:]` will
+ throw an exception.
+ * There's no way to update a `GHIssue` with new data from the server.
+ * There's no way to turn a `GHIssue` _back_ into JSON.
+ * `GHIssueState` shouldn't be encoded as-is. If the enum changes in the future,
+ existing archives might break.
+ * If the interface of `GHIssue` changes down the road, existing archives might
+ break.
+
+## Why Not Use Core Data?
+
+Core Data solves certain problems very well. If you need to execute complex
+queries across your data, handle a huge object graph with lots of relationships,
+or support undo and redo, Core Data is an excellent fit.
+
+It does, however, come with a couple of pain points:
+
+ * **There's still a lot of boilerplate.** Managed objects reduce some of the
+ boilerplate seen above, but Core Data has plenty of its own. Correctly
+ setting up a Core Data stack (with a persistent store and persistent store
+ coordinator) and executing fetches can take many lines of code.
+ * **It's hard to get right.** Even experienced developers can make mistakes
+ when using Core Data, and the framework is not forgiving.
+
+If you're just trying to access some JSON objects, Core Data can be a lot of
+work for little gain.
+
+Nonetheless, if you're using or want to use Core Data in your app already,
+Mantle can still be a convenient translation layer between the API and your
+managed model objects.
+
+## MTLModel
+
+Enter
+**[MTLModel](https://github.com/github/Mantle/blob/master/Mantle/MTLModel.h)**.
+This is what `GHIssue` looks like inheriting from `MTLModel`:
+
+```objc
+typedef enum : NSUInteger {
+ GHIssueStateOpen,
+ GHIssueStateClosed
+} GHIssueState;
+
+@interface GHIssue : MTLModel <MTLJSONSerializing>
+
+@property (nonatomic, copy, readonly) NSURL *URL;
+@property (nonatomic, copy, readonly) NSURL *HTMLURL;
+@property (nonatomic, copy, readonly) NSNumber *number;
+@property (nonatomic, assign, readonly) GHIssueState state;
+@property (nonatomic, copy, readonly) NSString *reporterLogin;
+@property (nonatomic, strong, readonly) GHUser *assignee;
+@property (nonatomic, copy, readonly) NSDate *updatedAt;
+
+@property (nonatomic, copy) NSString *title;
+@property (nonatomic, copy) NSString *body;
+
+@end
+```
+
+```objc
+@implementation GHIssue
+
++ (NSDateFormatter *)dateFormatter {
+ NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
+ dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US_POSIX"];
+ dateFormatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ss'Z'";
+ return dateFormatter;
+}
+
++ (NSDictionary *)JSONKeyPathsByPropertyKey {
+ return @{
+ @"URL": @"url",
+ @"HTMLURL": @"html_url",
+ @"reporterLogin": @"user.login",
+ @"assignee": @"assignee",
+ @"updatedAt": @"updated_at"
+ };
+}
+
++ (NSValueTransformer *)URLJSONTransformer {
+ return [NSValueTransformer valueTransformerForName:MTLURLValueTransformerName];
+}
+
++ (NSValueTransformer *)HTMLURLJSONTransformer {
+ return [NSValueTransformer valueTransformerForName:MTLURLValueTransformerName];
+}
+
++ (NSValueTransformer *)stateJSONTransformer {
+ return [NSValueTransformer mtl_valueMappingTransformerWithDictionary:@{
+ @"open": @(GHIssueStateOpen),
+ @"closed": @(GHIssueStateClosed)
+ }];
+}
+
++ (NSValueTransformer *)assigneeJSONTransformer {
+ return [NSValueTransformer mtl_JSONDictionaryTransformerWithModelClass:GHUser.class];
+}
+
++ (NSValueTransformer *)updatedAtJSONTransformer {
+ return [MTLValueTransformer reversibleTransformerWithForwardBlock:^(NSString *str) {
+ return [self.dateFormatter dateFromString:str];
+ } reverseBlock:^(NSDate *date) {
+ return [self.dateFormatter stringFromDate:date];
+ }];
+}
+
+@end
+```
+
+Notably absent from this version are implementations of `<NSCoding>`,
+`<NSCopying>`, `-isEqual:`, and `-hash`. By inspecting the `@property`
+declarations you have in your subclass, `MTLModel` can provide default
+implementations for all these methods.
+
+The problems with the original example all happen to be fixed as well:
+
+> If the `url` or `html_url` field is missing, `+[NSURL URLWithString:]` will throw an exception.
+
+The URL transformer we used (included in Mantle) returns `nil` if given a `nil`
+string.
+
+> There's no way to update a `GHIssue` with new data from the server.
+
+`MTLModel` has an extensible `-mergeValuesForKeysFromModel:` method, which makes
+it easy to specify how new model data should be integrated.
+
+> There's no way to turn a `GHIssue` _back_ into JSON.
+
+This is where reversible transformers really come in handy. `+[MTLJSONAdapter
+JSONDictionaryFromModel:]` can transform any model object conforming to
+`<MTLJSONSerializing>` back into a JSON dictionary. `+[MTLJSONAdapter
+JSONArrayForModels:]` is the same but turns an array of model objects into an JSON array of dictionaries.
+
+> If the interface of `GHIssue` changes down the road, existing archives might break.
+
+`MTLModel` automatically saves the version of the model object that was used for
+archival. When unarchiving, `-decodeValueForKey:withCoder:modelVersion:` will
+be invoked if overridden, giving you a convenient hook to upgrade old data.
+
+## MTLJSONSerializing
+
+In order to serialize your model objects from or into JSON, you need to
+implement `<MTLJSONSerializing>` in your `MTLModel` subclass. This allows you to
+use `MTLJSONAdapter` to convert your model objects from JSON and back:
+
+```objc
+NSError *error = nil;
+XYUser *user = [MTLJSONAdapter modelOfClass:XYUser.class fromJSONDictionary:JSONDictionary error:&error];
+```
+
+```objc
+NSDictionary *JSONDictionary = [MTLJSONAdapter JSONDictionaryFromModel:user];
+```
+
+### `+JSONKeyPathsByPropertyKey`
+
+The dictionary returned by this method specifies how your model object's
+properties map to the keys in the JSON representation. Properties that map to
+`NSNull` will not be present in the JSON representation, for example:
+
+```objc
+
+@interface XYUser : MTLModel
+
+@property (readonly, nonatomic, copy) NSString *name;
+@property (readonly, nonatomic, strong) NSDate *createdAt;
+
+@property (readonly, nonatomic, assign, getter = isMeUser) BOOL meUser;
+
+@end
+
+@implementation XYUser
+
++ (NSDictionary *)JSONKeyPathsByPropertyKey {
+ return @{
+ @"createdAt": @"created_at",
+ @"meUser": NSNull.null
+ };
+}
+
+@end
+```
+
+In this example, the `XYUser` class declares three properties that Mantle
+handles in different ways:
+
+- `name` is implicitly mapped to a key of the same name in the JSON
+ representation.
+- `createdAt` is converted to its snake case equivalent.
+- `meUser` is not serialized into JSON.
+
+Use `-[NSDictionary mtl_dictionaryByAddingEntriesFromDictionary:]` if your
+model's superclass also implements `MTLJSONSerializing` to merge their mappings.
+
+When deserializing JSON using
+`+[MTLJSONAdapter modelOfClass:fromJSONDictionary:error:]`, JSON keys that don't
+correspond to a property name or have an explicit mapping are ignored:
+
+```objc
+NSDictionary *JSONDictionary = @{
+ @"name": @"john",
+ @"created_at": @"2013/07/02 16:40:00 +0000",
+ @"plan": @"lite"
+};
+
+XYUser *user = [MTLJSONAdapter modelOfClass:XYUser.class fromJSONDictionary:JSONDictionary error:&error];
+```
+
+Here, the `plan` would be ignored since it neither matches a property name of
+`XYUser` nor is it otherwise mapped in `+JSONKeyPathsByPropertyKey`.
+
+### `+JSONTransformerForKey:`
+
+Implement this optional method to convert a property from a different type when
+deserializing from JSON.
+
+```
++ (NSValueTransformer *)JSONTransformerForKey:(NSString *)key {
+ if ([key isEqualToString:@"createdAt"]) {
+ return [NSValueTransformer valueTransformerForName:XYDateValueTransformerName];
+ }
+
+ return nil;
+}
+```
+
+For added convenience, if you implement `+<key>JSONTransformer`,
+`MTLJSONAdapter` will use the result of that method instead. For example, dates
+that are commonly represented as strings in JSON can be transformed to `NSDate`s
+like so:
+
+```objc
++ (NSValueTransformer *)createdAtJSONTransformer {
+ return [MTLValueTransformer reversibleTransformerWithForwardBlock:^(NSString *str) {
+ return [self.dateFormatter dateFromString:str];
+ } reverseBlock:^(NSDate *date) {
+ return [self.dateFormatter stringFromDate:date];
+ }];
+}
+```
+
+If the transformer is reversible, it will also be used when serializing the
+object into JSON.
+
+### `+classForParsingJSONDictionary:`
+
+If you are implementing a class cluster, implement this optional method to
+determine which subclass of your base class should be used when deserializing an
+object from JSON.
+
+```objc
+@interface XYMessage : MTLModel
+
+@end
+
+@interface XYTextMessage: XYMessage
+
+@property (readonly, nonatomic, copy) NSString *body;
+
+@end
+
+@interface XYPictureMessage : XYMessage
+
+@property (readonly, nonatomic, strong) NSURL *imageURL;
+
+@end
+
+@implementation XYMessage
+
++ (Class)classForParsingJSONDictionary:(NSDictionary *)JSONDictionary {
+ if (JSONDictionary[@"image_url"] != nil) {
+ return XYPictureMessage.class;
+ }
+
+ if (JSONDictionary[@"body"] != nil) {
+ return XYTextMessage.class;
+ }
+
+ NSAssert(NO, @"No matching class for the JSON dictionary '%@'.", JSONDictionary);
+ return self;
+}
+
+@end
+```
+
+`MTLJSONAdapter` will then pick the class based on the JSON dictionary you pass
+in:
+
+```objc
+NSDictionary *textMessage = @{
+ @"id": @1,
+ @"body": @"Hello World!"
+};
+
+NSDictionary *pictureMessage = @{
+ @"id": @2,
+ @"image_url": @"http://example.com/lolcat.gif"
+};
+
+XYTextMessage *messageA = [MTLJSONAdapter modelOfClass:XYMessage.class fromJSONDictionary:textMessage error:NULL];
+
+XYPictureMessage *messageB = [MTLJSONAdapter modelOfClass:XYMessage.class fromJSONDictionary:pictureMessage error:NULL];
+```
+
+## Persistence
+
+Mantle doesn't automatically persist your objects for you. However, `MTLModel`
+does conform to `<NSCoding>`, so model objects can be archived to disk using
+`NSKeyedArchiver`.
+
+If you need something more powerful, or want to avoid keeping your whole model
+in memory at once, Core Data may be a better choice.
+
+## System Requirements
+
+Mantle supports OS X 10.7+ and iOS 5.0+.
+
+## Importing Mantle
+
+To add Mantle to your application:
+
+ 1. Add the Mantle repository as a submodule of your application's repository.
+ 1. Run `script/bootstrap` from within the Mantle folder.
+ 1. Drag and drop `Mantle.xcodeproj` into your application's Xcode project or
+ workspace.
+ 1. On the "Build Phases" tab of your application target, add Mantle to the
+ "Link Binary With Libraries" phase.
+ * **On iOS**, add `libMantle.a`.
+ * **On OS X**, add `Mantle.framework`. Mantle must also be added to any
+ "Copy Frameworks" build phase. If you don't already have one, simply add a
+ "Copy Files" build phase and target the "Frameworks" destination.
+ 1. Add `"$(BUILD_ROOT)/../IntermediateBuildFilesPath/UninstalledProducts/include" $(inherited)`
+ to the "Header Search Paths" build setting (this is only
+ necessary for archive builds, but it has no negative effect otherwise).
+ 1. **For iOS targets**, add `-ObjC` to the "Other Linker Flags" build setting.
+ 1. **If you added Mantle to a project (not a workspace)**, you will also need
+ to add the appropriate Mantle target to the "Target Dependencies" of your
+ application.
+
+If you would prefer to use [CocoaPods](http://cocoapods.org), there are some
+[Mantle podspecs](https://github.com/CocoaPods/Specs/tree/master/Mantle) that
+have been generously contributed by third parties.
+
+If you’re instead developing Mantle on its own, use the `Mantle.xcworkspace` file.
+
+## License
+
+Mantle is released under the MIT license. See
+[LICENSE.md](https://github.com/github/Mantle/blob/master/LICENSE.md).
