Inspired by CSMapper and Mogenerator, US2MapperKit is an an extremely lightweight mapping framework designed specifically for Swift 1.2, and Swift 2.0.
Unlike previous frameworks, where an object model is manually created by the developer then retrofitted with a mapping framework at a later point, US2MapperKit takes a mapping-first approach. By mapping against dictionary data up front, US2MapperKit generates the model objects based on the mapping, and allows for the extensibility inspired by the Protocol-Oriented Programming talk at WWDC.
##Core Concept
The simple example above demonstrates the inner workings of the US2MapperKit. In this example we will attemp to map a Person object returned in the form a dictionary. The first step is to manually generate a plist representing the data that is being returned. This plist defines properties, data types, the mapping keys associated with the response dictionary, and any transformation that needs to be applied. Once defined, a build-time script will generate two model object files representing the model mapping.
The first class generated in the diagram represents the internal _Person.swift class, which contains script-generated property definitions, along two initializers, one required, and one fail-able. The generated fail-able initializer takes in a Dictionary<String, AnyObject> input value which is parsed to the model. The internal files purpose is to support the framework by mapping the response data and should not be modified by the developer since the script will regenerate it every time the project is built.
The second class generated is the Person.swift which inherits from the internal _Person.swift class. This provides a means for developer to append any custom logic, properties, or implementations of protocols as needed during the development process. This class is only generated once, and will never be overwritten during the build task. Thus updating the model mapping will not affect any logic defined in the external class.
##Features
- Auto generation of model objects via .plists files
- Optional & Non-Optional support for:
- String
- Int
- Double
- Float
- Bool
- Collections Support for:
- Array<AnyObject>
- Dictionary<String, AnyObject>
- Complex Type Support (stand alone, and in collections)
- Default Value Definitions
- Mapping Nested Values
- Complex Transformations
- Structs, Enums, Closures, Tuples via Transformations
##Basic Use
####Initialization with Dictionary
Once configured per the Installation instructions:
-
Create a plist model mapping and place it in the mapping folder defined during installation.
-
Build the target, navigate to the output directory defined during the installation process, and add the generated files to the project.
-
Map the data to an instance, call the fail-able initializer generated by US2MapperKit with the
Dictionary<String, AnyObject>data to parse.
let newInstance = TestModelObject(dataDictionary) ```
####Update with Dictionary
Once an instance has been initialized, we can pass a new dictionary with values to update for the current instance by calling updateWithDictionary(dictionary : Dictionary<String, AnyObject>?). Note that only the values which are being passed within will be updated, defaults values are ignored unline the initialization
let instance = TestModelObject(dataDictionary)
let newValuesDictionary = [... : ...]
// Updates the current values only with the new values received, defaults in mapping are ignored
instance.updateWithDictionary(newValuesDictionary)
####Examples
Below is a list of examples for the supported features by US2MapperKit. Each provides an overall view on how to setup the model mapping file, and short examples of the outputs generated by pre-packaged script within the framework.
- Optional Types
- Non-Optional Types
- Collection Types
- Complex Types
- Default Value Definitions
- Mapping Against Nested Values
- Custom Transformations
- Structs Mapping
- Enum Mapping
- Closures Mapping
- Tuples Mapping
##Troubleshooting
##Updates
##Future Enahancements
- Mapping Inheritance (Configuration to Inherit from NSManagedObject / Realm Object)
- Xcode Plug-in
License
The MIT License (MIT)
Copyright (c) 2015 ustwo studio inc (www.ustwo.com)
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.