diff --git a/.gitignore b/.gitignore index 8ccecd6..1d00516 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,4 @@ Carthage/Build .fastlane/report.xml .fastlane/xcodebuild-data *.coverage.txt +docs diff --git a/.jazzy.yaml b/.jazzy.yaml new file mode 100644 index 0000000..a2ead1c --- /dev/null +++ b/.jazzy.yaml @@ -0,0 +1,17 @@ +author_name: Daniel Thorpe +author_url: http://danthorpe.me +module_name: ValueCoding +module_version: 1.1.0 +github_url: https://github.com/danthorpe/ValueCoding +readme: README.md +podspec: ValueCoding.podspec + +swift_version: 2.1 +xcodebuild-arguments: -scheme,ValueCoding-iOS + +custom_categories: + - name: ValueCoding + children: + - CodingType + - ValueCoding + - SequenceType diff --git a/README.md b/README.md index 25bd917..888f177 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![](header.png) +![](https://raw.githubusercontent.com/danthorpe/ValueCoding/development/header.png) [![Build status](https://badge.buildkite.com/482fd5558d9ccf05b669c55f40450166033522f32314a1bbb2.svg)](https://buildkite.com/blindingskies/valuecoding) [![codecov.io](http://codecov.io/github/danthorpe/ValueCoding/coverage.svg?branch=development)](http://codecov.io/github/danthorpe/ValueCoding?branch=development) @@ -47,13 +47,13 @@ class FooCoder: NSObject, NSCoding, CodingType { If you are converting existing models from classes to values types, the `NSCoding` methods should look familiar, and hopefully you are able to reuse your existing code. -The framework provides static methods and properties for types which conform to `ValueCoding` with correct archivers. Therefore, given a value of `Foo`, you can encode it ready for serialization using `NSKeyedArchiver`. +The framework provides static methods and properties for types which conform to `ValueCoding` with valid coders. Therefore, given a value of `Foo`, you can encode it ready for archiving using `NSKeyedArchiver`. ```swift let data = NSKeyedArchiver.archivedDataWithRootObject(foo.encoded) ``` -and likewise, unarchiving (and decoding) can be done: +and likewise, decoding from unarchiving can be done: ```swift if let foo = Foo.decode(NSKeyedUnarchiver.unarchiveObjectWithData(data)) { @@ -70,14 +70,19 @@ let foos = Set(arrayLiteral: Foo(), Foo(), Foo()) let data = NSKeyedArchiver.archivedDataWithRootObject(foos.encoded) ``` -When decoding an `NSArray`, perform a conditional cast to `[AnyObject]` before passing it to `decode`. The result will be an `Array` which will be empty if the object was not cast successfully. In addition, any members of `[AnyObject]` which did not decode will filtered from the result. This means that the length of the result will be less than the original encoded array if there was an issue decoding. +When decoding an `NSArray`, perform a conditional cast to `[AnyObject]` before passing it to `decode`. The result will be an `Array` which will be empty if the object was not cast successfully. In addition, any members of `[AnyObject]` which did not decode will be filtered from the result. This means that the length of the result will be less than the original encoded array if there was an issue decoding. ```swift let foos = Foo.decode(NSKeyedUnarchiver.unarchiveObjectWithData(data) as? [AnyObject]) ``` +### CoderType Examples + +The [Money](https://github.com/danthorpe/Money) framework contains more examples of implementing `ValueCoding`. Including the generic type [`FXTransactionCoder`](https://github.com/danthorpe/Money/blob/development/Money/Shared/FX/FX.swift#L467). + +The [YapDatabaseExtensions](https://github.com/danthorpe/YapDatabaseExtension) framework relies heavily on `ValueCoding`. For more examples of generic where constraints see its [Functional API](https://github.com/danthorpe/YapDatabaseExtensions/tree/development/YapDatabaseExtensions/Shared/Functional). ### Installation -ValueCoding builds as a cross platform (iOS, OS X, watchOS) extension compatible framework. It is also available via CocoaPods +ValueCoding builds as a cross platform (iOS, OS X, watchOS, tvOS) extension compatible framework. It is also available via CocoaPods ```ruby pod 'ValueCoding' diff --git a/ValueCoding.xcodeproj/xcshareddata/xcschemes/ValueCoding-tvOS.xcscheme b/ValueCoding.xcodeproj/xcshareddata/xcschemes/ValueCoding-tvOS.xcscheme index 3e35f75..be9074e 100644 --- a/ValueCoding.xcodeproj/xcshareddata/xcschemes/ValueCoding-tvOS.xcscheme +++ b/ValueCoding.xcodeproj/xcshareddata/xcschemes/ValueCoding-tvOS.xcscheme @@ -15,7 +15,7 @@ @@ -43,7 +43,7 @@ @@ -65,7 +65,7 @@ @@ -83,7 +83,7 @@ diff --git a/ValueCoding/ValueCoding.swift b/ValueCoding/ValueCoding.swift index 6ea6ab4..623f02c 100644 --- a/ValueCoding/ValueCoding.swift +++ b/ValueCoding/ValueCoding.swift @@ -16,6 +16,20 @@ encode/decode value types. */ public protocol CodingType { + /** + The type of the composed value, ValueType + + Bear in mind that there are no constraints on this + type. However, in reality when working with generic + types which require coding, it will be necessary to + constrain your generic clauses like this: + + ```swift + func foo() + ``` + + - see: ValueCoding + */ typealias ValueType /// The value type which is being encoded/decoded @@ -32,6 +46,12 @@ A generic protocol for value types which require coding. */ public protocol ValueCoding { + + /** + The Coder which implements CodingType + + - see: CodingType + */ typealias Coder: CodingType } @@ -48,8 +68,7 @@ extension CodingType where ValueType: ValueCoding, ValueType.Coder == Self { } } -extension SequenceType - where +extension SequenceType where Generator.Element: CodingType { /// Access the values from a sequence of coders. @@ -106,8 +125,7 @@ extension ValueCoding where Coder: NSCoding, Coder.ValueType == Self { } } -extension SequenceType - where +extension SequenceType where Generator.Element: ValueCoding, Generator.Element.Coder: NSCoding, Generator.Element.Coder.ValueType == Generator.Element {