Commit 0d633222 authored by Eyad Hasan's avatar Eyad Hasan
Browse files

Added object mapper

I added object mapper since it's recommended to be used with swift.  also @rhitt unban me.
parent 6cada287
......@@ -7,7 +7,7 @@ target 'WhatsOpen' do
pod 'RealmSwift'
#pod 'ObjectMapper+Realm', '~> 0.2'
pod 'ObjectMapper', '~> 2.2'
#pod 'Segmentio', '~> 2.1'
......
PODS:
- ObjectMapper (2.2.8)
- Realm (2.10.0):
- Realm/Headers (= 2.10.0)
- Realm/Headers (2.10.0)
......@@ -6,12 +7,14 @@ PODS:
- Realm (= 2.10.0)
DEPENDENCIES:
- ObjectMapper (~> 2.2)
- RealmSwift
SPEC CHECKSUMS:
ObjectMapper: 3d571bb5af471c779e1160828cd9ad5c4ef90958
Realm: 98b3a25643cf6b3e07d2b99fb43fe0eb9c801dec
RealmSwift: 34073ad3a31232bbaf7c0db898c037940284cba2
PODFILE CHECKSUM: b8c4ac0f68e1021098d7016accb14cf642240f47
PODFILE CHECKSUM: 2d5f357c11583d1910eee9ef03105571633f7ad2
COCOAPODS: 1.2.1
PODS:
- ObjectMapper (2.2.8)
- Realm (2.10.0):
- Realm/Headers (= 2.10.0)
- Realm/Headers (2.10.0)
......@@ -6,12 +7,14 @@ PODS:
- Realm (= 2.10.0)
DEPENDENCIES:
- ObjectMapper (~> 2.2)
- RealmSwift
SPEC CHECKSUMS:
ObjectMapper: 3d571bb5af471c779e1160828cd9ad5c4ef90958
Realm: 98b3a25643cf6b3e07d2b99fb43fe0eb9c801dec
RealmSwift: 34073ad3a31232bbaf7c0db898c037940284cba2
PODFILE CHECKSUM: b8c4ac0f68e1021098d7016accb14cf642240f47
PODFILE CHECKSUM: 2d5f357c11583d1910eee9ef03105571633f7ad2
COCOAPODS: 1.2.1
The MIT License (MIT)
Copyright (c) 2014 Hearst
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.
# ObjectMapper-CN-Guide
> 文档由Swift老司机活动中心负责翻译,欢迎关注[@SwiftOldDriver](http://weibo.com/6062089411)。翻译有问题可以到 [ObjectMapper-CN-Guide](https://github.com/SwiftOldDriver/ObjectMapper-CN-Guide) 提 PR。
[ObjectMapper](https://github.com/Hearst-DD/ObjectMapper) 是一个使用 Swift 编写的用于 model 对象(类和结构体)和 JSON 之间转换的框架。
- [特性](#特性)
- [基础使用方法](#基础使用方法)
- [映射嵌套对象](#映射嵌套对象)
- [自定义转换规则](#自定义转换规则)
- [继承](#继承)
- [泛型对象](#泛型对象)
- [映射时的上下文对象](#映射时的上下文对象)
- [ObjectMapper + Alamofire](#objectmapper--alamofire)
- [ObjectMapper + Realm](#objectmapper--realm)
- [待完成](#待完成)
- [安装](#安装)
# 特性:
- 把 JSON 映射成对象
- 把对象映射 JSON
- 支持嵌套对象 (单独的成员变量、在数组或字典中都可以)
- 在转换过程支持自定义规则
- 支持结构体( Struct )
- [Immutable support](#immutablemappable-protocol-beta) (目前还在 beta )
# 基础使用方法
为了支持映射,类或者结构体只需要实现```Mappable```协议。这个协议包含以下方法:
```swift
init?(map: Map)
mutating func mapping(map: Map)
```
ObjectMapper使用自定义的```<-``` 运算符来声明成员变量和 JSON 的映射关系。
```swift
class User: Mappable {
var username: String?
var age: Int?
var weight: Double!
var array: [AnyObject]?
var dictionary: [String : AnyObject] = [:]
var bestFriend: User? // 嵌套的 User 对象
var friends: [User]? // Users 的数组
var birthday: NSDate?
required init?(map: Map) {
}
// Mappable
func mapping(map: Map) {
username <- map["username"]
age <- map["age"]
weight <- map["weight"]
array <- map["arr"]
dictionary <- map["dict"]
bestFriend <- map["best_friend"]
friends <- map["friends"]
birthday <- (map["birthday"], DateTransform())
}
}
struct Temperature: Mappable {
var celsius: Double?
var fahrenheit: Double?
init?(map: Map) {
}
mutating func mapping(map: Map) {
celsius <- map["celsius"]
fahrenheit <- map["fahrenheit"]
}
}
```
一旦你的对象实现了 `Mappable`, ObjectMapper就可以让你轻松的实现和 JSON 之间的转换。
把 JSON 字符串转成 model 对象:
```swift
let user = User(JSONString: JSONString)
```
把一个 model 转成 JSON 字符串:
```swift
let JSONString = user.toJSONString(prettyPrint: true)
```
也可以使用`Mapper.swift`类来完成转换(这个类还额外提供了一些函数来处理一些特殊的情况:
```swift
// 把 JSON 字符串转成 Model
let user = Mapper<User>().map(JSONString: JSONString)
// 根据 Model 生成 JSON 字符串
let JSONString = Mapper().toJSONString(user, prettyPrint: true)
```
ObjectMapper支持以下的类型映射到对象中:
- `Int`
- `Bool`
- `Double`
- `Float`
- `String`
- `RawRepresentable` (枚举)
- `Array<AnyObject>`
- `Dictionary<String, AnyObject>`
- `Object<T: Mappable>`
- `Array<T: Mappable>`
- `Array<Array<T: Mappable>>`
- `Set<T: Mappable>`
- `Dictionary<String, T: Mappable>`
- `Dictionary<String, Array<T: Mappable>>`
- 以上所有的 Optional 类型
- 以上所有的隐式强制解包类型(Implicitly Unwrapped Optional)
## `Mappable` 协议
#### `mutating func mapping(map: Map)`
所有的映射最后都会调用到这个函数。当解析 JSON 时,这个函数会在对象创建成功后被执行。当生成 JSON 时就只有这个函数会被对象调用。
#### `init?(map: Map)`
这个可失败的初始化函数是 ObjectMapper 创建对象的时候使用的。开发者可以通过这个函数在映射前校验 JSON 。如果在这个方法里返回 nil 就不会执行 `mapping` 函数。可以通过传入的保存着 JSON 的 `Map` 对象进行校验:
```swift
required init?(map: Map){
// 检查 JSON 里是否有一定要有的 "name" 属性
if map.JSONDictionary["name"] == nil {
return nil
}
}
```
## `StaticMappable` 协议
`StaticMappable``Mappable` 之外的另一种选择。 这个协议可以让开发者通过一个静态函数初始化对象而不是通过 `init?(map: Map)`
注意: `StaticMappable``Mappable` 都继承了 `BaseMappable` 协议。 `BaseMappable` 协议声明了 `mapping(map: Map)` 函数。
#### `static func objectForMapping(map: Map) -> BaseMappable?`
ObjectMapper 使用这个函数获取对象后进行映射。开发者需要在这个函数里返回一个实现 `BaseMappable` 对象的实例。这个函数也可以用于:
- 在对象进行映射前校验 JSON
- 提供一个缓存过的对象用于映射
- 返回另外一种类型的对象(当然是必须实现了 BaseMappable)用于映射。比如你可能通过检查 JSON 推断出用于映射的对象 ([看这个例子](https://github.com/Hearst-DD/ObjectMapper/blob/master/ObjectMapperTests/ClassClusterTests.swift#L62))。
如果你需要在 extension 里实现 ObjectMapper,你需要选择这个协议而不是 `Mappable`
## `ImmutableMappable` Protocol (Beta)
> ⚠️ 这个特性还处于 Beta 阶段。正式发布时 API 可能会完全不同。
使用 `ImmutableMappable` 可以映射不可变的属性。下面的表格展示了 `ImmutableMappable``Mappable` 的不同:
<table>
<tr>
<th>ImmutableMappable</th>
<th>Mappable</th>
</tr>
<tr>
<th colspan="2">Properties</th>
</tr>
<tr>
<td>
<pre>
<strong>let</strong> id: Int
<strong>let</strong> name: String?
</pre>
</td>
<td>
<pre>
var id: Int!
var name: String?
</pre>
</td>
</tr>
<tr>
<th colspan="2">JSON -> Model</th>
</tr>
<tr>
<td>
<pre>
init(map: Map) <strong>throws</strong> {
id = <strong>try</strong> map.value("id")
name = <strong>try?</strong> map.value("name")
}
</pre>
</td>
<td>
<pre>
mutating func mapping(map: Map) {
id <- map["id"]
name <- map["name"]
}
</pre>
</td>
</tr>
<tr>
<th colspan="2">Model -> JSON</th>
</tr>
<tr>
<td>
<pre>
mutating func mapping(map: Map) {
id <strong>>>></strong> map["id"]
name <strong>>>></strong> map["name"]
}
</pre>
</td>
<td>
<pre>
mutating func mapping(map: Map) {
id <- map["id"]
name <- map["name"]
}
</pre>
</td>
</tr>
<tr>
<th colspan="2">Initializing</th>
</tr>
<tr>
<td>
<pre>
<strong>try</strong> User(JSONString: JSONString)
</pre>
</td>
<td>
<pre>
User(JSONString: JSONString)
</pre>
</td>
</tr>
</table>
#### `init(map: Map) throws`
这个可能抛出异常的初始化函数用于在提供的 `Map` 里映射不可变属性。每个不可变的初始化属性都要在这个初始化函数里初始化。
当发生下列情况时初始化函数会抛出一个错误:
- `Map` 根据提供的键名获取不到对应值
- `Map` 使用 `Transform` 后没有得到值
`ImmutableMappable` 使用 `Map.value(_:using:)` 方法从 `Map` 中获取值。因为可能抛出异常,这个方法在使用时需要使用 `try` 关键字。 `Optional` 的属性可以简单的用 `try?` 处理。
```swift
init(map: Map) throws {
name = try map.value("name") // throws an error when it fails
createdAt = try map.value("createdAt", using: DateTransform()) // throws an error when it fails
updatedAt = try? map.value("updatedAt", using: DateTransform()) // optional
posts = (try? map.value("posts")) ?? [] // optional + default value
}
```
#### `mutating func mapping(map: Map)`
这个方法是在 Model 转回 JSON 时调用的。因为不可变的属性不能被 `<-` 映射,所以映射回来时需要使用 `>>>`
```swift
mutating func mapping(map: Map) {
name >>> map["name"]
createdAt >>> (map["createdAt"], DateTransform())
updatedAt >>> (map["updatedAt"], DateTransform())
posts >>> map["posts"]
}
```
# 轻松映射嵌套对象
ObjectMapper 支持使用点语法来轻松实现嵌套对象的映射。比如有如下的 JSON 字符串:
```json
"distance" : {
"text" : "102 ft",
"value" : 31
}
```
你可以通过这种写法直接访问到嵌套对象:
```swift
func mapping(map: Map) {
distance <- map["distance.value"]
}
```
嵌套的键名也支持访问数组中的值。如果有一个返回的 JSON 是一个包含 distance 的数组,可以通过这种写法访问:
```
distance <- map["distances.0.value"]
```
如果你的键名刚好含有 `.` 符号,你需要特别声明关闭上面提到的获取嵌套对象功能:
```swift
func mapping(map: Map) {
identifier <- map["app.identifier", nested: false]
}
```
如果刚好有嵌套的对象的键名还有 `.` ,可以在中间加入一个自定义的分割符([#629](https://github.com/Hearst-DD/ObjectMapper/pull/629)):
```swift
func mapping(map: Map) {
appName <- map["com.myapp.info->com.myapp.name", delimiter: "->"]
}
```
这种情况的 JSON 是这样的:
```json
"com.myapp.info" : {
"com.myapp.name" : "SwiftOldDriver"
}
```
# 自定义转换规则
ObjectMapper 也支持在映射时自定义转换规则。如果要使用自定义转换,创建一个 tuple(元祖)包含 ```map["field_name"]``` 和你要使用的变换放在 ```<-``` 的右边:
```swift
birthday <- (map["birthday"], DateTransform())
```
当解析 JSON 时上面的转换会把 JSON 里面的 Int 值转成一个 NSDate ,如果是对象转为 JSON 时,则会把 NSDate 对象转成 Int 值。
只要实现```TransformType``` 协议就可以轻松的创建自定义的转换规则:
```swift
public protocol TransformType {
associatedtype Object
associatedtype JSON
func transformFromJSON(_ value: Any?) -> Object?
func transformToJSON(_ value: Object?) -> JSON?
}
```
### TransformOf
大多数情况下你都可以使用框架提供的转换类 ```TransformOf``` 来快速的实现一个期望的转换。 ```TransformOf``` 的初始化需要两个类型和两个闭包。两个类型声明了转换的目标类型和源类型,闭包则实现具体转换逻辑。
举个例子,如果你想要把一个 JSON 字符串转成 Int ,你可以像这样使用 ```TransformOf```
```swift
let transform = TransformOf<Int, String>(fromJSON: { (value: String?) -> Int? in
// 把值从 String? 转成 Int?
return Int(value!)
}, toJSON: { (value: Int?) -> String? in
// 把值从 Int? 转成 String?
if let value = value {
return String(value)
}
return nil
})
id <- (map["id"], transform)
```
这是一种更省略的写法:
```swift
id <- (map["id"], TransformOf<Int, String>(fromJSON: { Int($0!) }, toJSON: { $0.map { String($0) } }))
```
# 继承
实现了 ```Mappable``` 协议的类可以容易的被继承。当继承一个 mappable 的类时,使用这样的结构:
```swift
class Base: Mappable {
var base: String?
required init?(map: Map) {
}
func mapping(map: Map) {
base <- map["base"]
}
}
class Subclass: Base {
var sub: String?
required init?(map: Map) {
super.init(map)
}
override func mapping(map: Map) {
super.mapping(map)
sub <- map["sub"]
}
}
```
注意确认子类中的实现调用了父类中正确的初始化器和映射函数。
# 泛型对象
ObjectMapper 可以处理泛型只要这个泛型也实现了`Mappable`协议。看这个例子:
```swift
class Result<T: Mappable>: Mappable {
var result: T?
required init?(map: Map){
}
func mapping(map: Map) {
result <- map["result"]
}
}
let result = Mapper<Result<User>>().map(JSON)
```
# 映射时的上下文对象
`Map` 是在映射时传入的对象,带有一个 optional `MapContext` 对象,开发者可以通过使用这个对象在映射时传入一些信息。
为了使用这个特性,需要先创建一个对象实现了 `MapContext` 协议(这个协议是空的),然后在初始化时传入 `Mapper` 中。
```swift
struct Context: MapContext {
var importantMappingInfo = "映射时需要知道的额外信息"
}
class User: Mappable {
var name: String?
required init?(map: Map){
}
func mapping(map: Map){
if let context = map.context as? Context {
// 获取到额外的信息
}
}
}
let context = Context()
let user = Mapper<User>(context: context).map(JSONString)
```
# ObjectMapper + Alamofire
如果网络层你使用的是 [Alamofire](https://github.com/Alamofire/Alamofire) ,并且你希望把返回的结果转换成 Swift 对象,你可以使用 [AlamofireObjectMapper](https://github.com/tristanhimmelman/AlamofireObjectMapper) 。这是一个使用 ObjectMapper 实现的把返回的 JSON 自动转成 Swift 对象的 Alamofire 的扩展。
# ObjectMapper + Realm
ObjectMapper 可以和 Realm 一起配合使用。使用下面的声明结构就可以使用 ObjectMapper 生成 Realm 对象:
```swift
class Model: Object, Mappable {
dynamic var name = ""
required convenience init?(map: Map) {
self.init()
}
func mapping(map: Map) {
name <- map["name"]
}
}
```
如果你想要序列化相关联的 RealmObject,你可以使用 [ObjectMapper+Realm](https://github.com/jakenberg/ObjectMapper-Realm)。这是一个简单的 Realm 扩展,用于把任意的 JSON 序列化成 Realm 的类(ealm's List class。)
注意:使用 ObjectMappers 的 `toJSON` 函数来生成 JSON 字符串只在 Realm 的写事务中有效(write transaction)。这是因为 ObjectMapper 在解析和生成时在映射函数( `<-` )中使用 `inout` 作为标记( flag )。Realm 会检测到标记并且强制要求 `toJSON` 函数只能在一个写的事务中调用,即使这个对象并没有被修改。
# 待完成
- 改善错误的处理。可能使用 `throws` 来处理。
- 相关类的文档完善
# 安装
### Cocoapods
如果你的项目使用 [CocoaPods 0.36 及以上](http://blog.cocoapods.org/Pod-Authors-Guide-to-CocoaPods-Frameworks/) 的版本,你可以把下面内容添加到在 `Podfile` 中,将 ObjectMapper 添加到你的项目中:
```ruby
pod 'ObjectMapper', '~> 2.2'
```
### Carthage
如果你的项目使用 [Carthage](https://github.com/Carthage/Carthage) ,你可以把下面的内容添加到 `Cartfile` 中,将 ObjectMapper 的依赖到你的项目中:
```
github "Hearst-DD/ObjectMapper" ~> 2.2
```
### Swift Package Manager
如果你的项目使用 [Swift Package Manager](https://swift.org/package-manager/) ,那么你可以把下面内容添加到 `Package.swift` 中的 `dependencies` 数组中,将 ObjectMapper 的依赖到你的项目中:
```swift
.Package(url: "https://github.com/Hearst-DD/ObjectMapper.git", majorVersion: 2, minor: 2),
```
### Submodule
此外,ObjectMapper 也可以作为一个 submodule 添加到项目中:
1. 打开终端,使用 `cd` 命令进入项目文件的根目录下,然后在终端中输入 `git submodule add https://github.com/Hearst-DD/ObjectMapper.git` ,把 ObjectMapper 作为项目的一个 [submodule](http://git-scm.com/docs/git-submodule) 添加进来。
2. 打开 `ObjectMapper` 文件,并将 `ObjectMapper.xcodeproj` 拖进你 app 项目的文件导航中。
3. 在 Xcode 中,文件导航中点击蓝色项目图标进入到 target 配置界面,在侧边栏的 "TARGETS" 下选择主工程对应的target。
4. 确保 `ObjectMapper.framework` 的部署版本( deployment target )和主工程的部署版本保持一致。
5. 在配置界面的顶部选项栏中,打开 "Build Phases" 面板。
6. 展开 "Target Dependencies" 组,并添加 `ObjectMapper.framework`
7. 点击面板左上角的 `+` 按钮,选择 "New Copy Files Phase"。将这个阶段重命名为 "Copy Frameworks",设置 "Destination" 为 "Frameworks",最后添加 `ObjectMapper.framework`
//
// CustomDateFormatTransform.swift
// ObjectMapper
//
// Created by Dan McCracken on 3/8/15.
//
// The MIT License (MIT)
//
// Copyright (c) 2014-2016 Hearst
//
// 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.
import Foundation
open class CustomDateFormatTransform: DateFormatterTransform {
public init(formatString: String) {
let formatter = DateFormatter()
formatter.locale = Locale(identifier: "en_US_POSIX")
formatter.dateFormat = formatString
super.init(dateFormatter: formatter)
}
}
//
// DataTransform.swift
// ObjectMapper
//
// Created by Yagrushkin, Evgeny on 8/30/16.
//
// The MIT License (MIT)