RestKit/RestKit — pull request #1588 by blakewatters (2013-09-05 14:23:21+00:00)
Title: Value Transformation Architecture

**Squashed pull request moved from https://github.com/RestKit/RestKit/pull/1583**

This pull request adds a new subsystem to the object mapping engine that enables the use of pluggable value transformers. Common value transformations such as from NSString <-> NSDate and NSNumber <-> NSString have always been a core part of the feature-set of RestKit but up to now have required direct customization of the library source code and could only be changed on a global basis. All value transformations that were previously handled within the internals of RKMappingOperation have been factored out into simple standalone transformers. The transformer API is completely extensible and customizable and transfers full control of the mapping process from the framework back to the end developer.

The API has the following design properties:

Transformers are implemented via a simple RKValueTransforming protocol. The protocol has a single required method: transformValue:toValue:ofClass:error: and an optional method for validating transformations validateTransformationFromClass:toClass:.
To ease implementation, a concrete RKBlockValueTransformer class is provided that enables the end-developer to implement a transformer via blocks. For third-party extensions, an abstract RKValueTransformer base class is provided as well.
All previous internally implemented transformations are provided as singleton instances on RKValueTransformer.
To facilitate transforming a value into an unknown target representation with an arbitrary collection of value transformers the RKCompoundValueTransformer class is provided. This class itself implements RKValueTransforming and will attempt to transform an input value with each of the transformers it contains in programmer defined order, enabling a simple transformation chain to be expressed.
The previous Date and Time formatting API's have been harmonized with the new value transformation API by making NSDateFormatter conform to the RKValueTransforming protocol.
It is notable that this API intentionally does not make use of the NSValueTransformer class provided by Cocoa. The API was not a clean architectural fit with the needs of RestKit and the implementation contained in the PR is quite a bit simpler and more straight-forward than an NSValueTransformer based implementation would be (we walked quite a ways down this road before changing gears).

Full test coverage is implemented and API documentation should be adequate. Comments and feedback are most welcome.