Serialization/Encoding rename and extension of Encoder API surface

Author: dehesa

README.md

@@ -37,7 +37,7 @@ You can choose to add the library through SPM or Cocoapods:
     let package = Package(
         /* Your package name, supported platforms, and generated products go here */
         dependencies: [
-            .package(url: "https://github.com/dehesa/CodableCSV.git", .upToNextMinor(from: "0.5.0"))
+            .package(url: "https://github.com/dehesa/CodableCSV.git", .upToNextMinor(from: "0.5.1"))
         ],
         targets: [
             .target(name: /* Your target name here */, dependencies: ["CodableCSV"])
@@ -48,7 +48,7 @@ You can choose to add the library through SPM or Cocoapods:
 -   [Cocoapods](https://cocoapods.org).
 
     ```
-    pod 'CodableCSV', '~> 0.5.0'
+    pod 'CodableCSV', '~> 0.5.1'
     ```
 
 </p></details>
@@ -175,17 +175,17 @@ let reader = CSVReader(input: ...) {
 
 A `CSVWriter` encodes CSV information into a specified target (i.e. a `String`, or `Data`, or a file). It can be used at a _high-level_, by encoding completely a prepared set of information; or at a _low-level_, in which case rows or fields can be writen individually.
 
--   Complete CSV rows serialization.
+-   Complete CSV rows encoding.
 
     ```swift
     let input = [
         ["numA", "numB", "name"        ],
         ["1"   , "2"   , "Marcos"      ],
         ["4"   , "5"   , "Marine-Anaïs"]
     ]
-    let data   = try CSVWriter.serialize(rows: input)
-    let string = try CSVWriter.serialize(rows: input, into: String.self)
-    try CSVWriter.serialize(rows: input, into: URL("~/Desktop/Test.csv")!, append: false)
+    let data   = try CSVWriter.encode(rows: input)
+    let string = try CSVWriter.encode(rows: input, into: String.self)
+    try CSVWriter.encode(rows: input, into: URL("~/Desktop/Test.csv")!, append: false)
     ```
 
 -   Row-by-row encoding.
@@ -254,7 +254,7 @@ A `CSVWriter` encodes CSV information into a specified target (i.e. a `String`,
 
 -   `bomStrategy` (default: `.convention`) indicates whether a Byte Order Marker will be included at the beginning of the CSV representation.
 
-    The OS convention is that BOMs are never writen, except when `.utf16`, `.utf32`, or `.unicode` string encodings are specified. You could however indicate that you always want the BOM writen (`.always`) or that is never writer (`.never`).
+    The OS convention is that BOMs are never writen, except when `.utf16`, `.utf32`, or `.unicode` string encodings are specified. You could however indicate that you always want the BOM writen (`.always`) or that is never writen (`.never`).
 
 The configuration values are set during initialization and can be passed to the `CSWriter` instance through a structure or with a convenience closure syntax:
 

docs/SUPPORT.md

@@ -2,7 +2,7 @@
 
 Here is a helpful list of "where to get help" depending on the topic:
 
--   **How to use [CodableCSV](https://www.github.com/dehesa/CodableCSV)?**
+-   **How to use CodableCSV?**
 
     The first place to look is the [README file](https://github.com/dehesa/CodableCSV/blob/master/README.md). It is kept updated and there is a wealth of information under each right-pointing [caret](https://en.wikipedia.org/wiki/Caret). Information spans from basic usage to tips on how to squeeze the best performance.
 
@@ -20,11 +20,11 @@ Here is a helpful list of "where to get help" depending on the topic:
 
     For complex queries, go to the [Swift forums](https://forums.swift.org), specifically the [_Using Swift_](https://forums.swift.org/c/swift-users/15) category, setting the search tag to [_codable_](https://forums.swift.org/tags/c/swift-users/15/codable).
 
--   **How to contribute to [CodableCSV](https://www.github.com/dehesa/CodableCSV)?**
+-   **How to contribute to CodableCSV?**
 
-    This project uses the standard [CONTRIBUTING.md](docs/CONTRIBUTING.md) file explaining the contribution guidelines. This same file also has a section on "where to start contributing", in case you want to contribute but you are unsure where to start.
+    This project uses the standard [CONTRIBUTING.md](CONTRIBUTING.md) file explaining the contribution guidelines. This same file also has a section on "where to start contributing", in case you want to contribute but you are unsure where to start.
 
-    Also take a look at the Github's [projects page](https://github.com/dehesa/CodableCSV/projects) where you can see the project's Kanban board, or at a higher level, take a look at the [Roadmap graph](docs/Assets/Roadmap.svg).
+    Also take a look at the Github's [projects page](https://github.com/dehesa/CodableCSV/projects) where you can see the project's Kanban board, or at a higher level, take a look at the [Roadmap graph](Assets/Roadmap.svg).
 
 -   **What is the Comma-separated values format?**
 

sources/Active/Writer/WriterAPI.swift

@@ -66,7 +66,7 @@ extension CSVWriter {
     /// - parameter configuration: Configuration values specifying how the CSV output should look like.
     /// - throws: `CSVError<CSVWriter>` exclusively.
     /// - returns: Data blob in a CSV format.
-    @inlinable public static func serialize<S:Sequence,C:Collection>(rows: S, configuration: Configuration = .init()) throws -> Data where S.Element==C, C.Element==String {
+    @inlinable public static func encode<S:Sequence,C:Collection>(rows: S, configuration: Configuration = .init()) throws -> Data where S.Element==C, C.Element==String {
         let writer = try CSVWriter(configuration: configuration)
         for row in rows {
             try writer.write(row: row)
@@ -82,8 +82,8 @@ extension CSVWriter {
     /// - parameter configuration: Configuration values specifying how the CSV output should look like.
     /// - throws: `CSVError<CSVWriter>` exclusively.
     /// - returns: Swift `String` containing the formatted CSV data.
-    @inlinable public static func serialize<S:Sequence,C:Collection>(rows: S, into type: String.Type, configuration: Configuration = .init()) throws -> String where S.Element==C, C.Element==String {
-        let data = try CSVWriter.serialize(rows: rows, configuration: configuration)
+    @inlinable public static func encode<S:Sequence,C:Collection>(rows: S, into type: String.Type, configuration: Configuration = .init()) throws -> String where S.Element==C, C.Element==String {
+        let data = try CSVWriter.encode(rows: rows, configuration: configuration)
         return String(data: data, encoding: configuration.encoding ?? .utf8)!
     }
 
@@ -93,7 +93,7 @@ extension CSVWriter {
     /// - parameter append: In case an existing file is under the given URL, this Boolean indicates that the information will be appended to the file (`true`), or the file will be overwritten (`false`).
     /// - parameter configuration: Configuration values specifying how the CSV output should look like.
     /// - throws: `CSVError<CSVWriter>` exclusively.
-    @inlinable public static func serialize<S:Sequence,C:Collection>(rows: S, into fileURL: URL, append: Bool, configuration: Configuration = .init()) throws where S.Element==C, C.Element==String {
+    @inlinable public static func encode<S:Sequence,C:Collection>(rows: S, into fileURL: URL, append: Bool, configuration: Configuration = .init()) throws where S.Element==C, C.Element==String {
         let writer = try CSVWriter(fileURL: fileURL, append: append, configuration: configuration)
         for row in rows {
             try writer.write(row: row)
@@ -111,10 +111,10 @@ extension CSVWriter {
     /// - parameter configuration: Default configuration values for the `CSVWriter`.
     /// - throws: `CSVError<CSVWriter>` exclusively.
     /// - returns: Data blob in a CSV format.
-    @inlinable public static func serialize<S:Sequence,C:Collection>(rows: S, setter: (_ configuration: inout Configuration) -> Void) throws -> Data where S.Element==C, C.Element==String {
+    @inlinable public static func encode<S:Sequence,C:Collection>(rows: S, setter: (_ configuration: inout Configuration) -> Void) throws -> Data where S.Element==C, C.Element==String {
         var configuration = Configuration()
         setter(&configuration)
-        return try CSVWriter.serialize(rows: rows, configuration: configuration)
+        return try CSVWriter.encode(rows: rows, configuration: configuration)
     }
 
 
@@ -125,10 +125,10 @@ extension CSVWriter {
     /// - parameter configuration: Default configuration values for the `CSVWriter`.
     /// - throws: `CSVError<CSVWriter>` exclusively.
     /// - returns: Swift `String` containing the formatted CSV data.
-    @inlinable public static func serialize<S:Sequence,C:Collection>(rows: S, into type: String.Type, setter: (_ configuration: inout Configuration) -> Void) throws -> String where S.Element==C, C.Element==String {
+    @inlinable public static func encode<S:Sequence,C:Collection>(rows: S, into type: String.Type, setter: (_ configuration: inout Configuration) -> Void) throws -> String where S.Element==C, C.Element==String {
         var configuration = Configuration()
         setter(&configuration)
-        return try CSVWriter.serialize(rows: rows, into: type, configuration: configuration)
+        return try CSVWriter.encode(rows: rows, into: type, configuration: configuration)
     }
 
     /// Creates a file with the CSV-encoded representation of the `rows` supplied.
@@ -138,10 +138,10 @@ extension CSVWriter {
     /// - parameter setter: Closure receiving the default configuration values and gives you the possibility to change them.
     /// - parameter configuration: Default configuration values for the `CSVWriter`.
     /// - throws: `CSVError<CSVWriter>` exclusively.
-    @inlinable public static func serialize<S:Sequence,C:Collection>(row: S, into fileURL: URL, append: Bool, setter: (_ configuration: inout Configuration) -> Void) throws where S.Element==C, C.Element==String {
+    @inlinable public static func encode<S:Sequence,C:Collection>(rows: S, into fileURL: URL, append: Bool, setter: (_ configuration: inout Configuration) -> Void) throws where S.Element==C, C.Element==String {
         var configuration = Configuration()
         setter(&configuration)
-        try CSVWriter.serialize(rows: row, into: fileURL, append: append, configuration: configuration)
+        try CSVWriter.encode(rows: rows, into: fileURL, append: append, configuration: configuration)
     }
 }
 
@@ -163,3 +163,37 @@ fileprivate extension CSVWriter.Error {
               userInfo: ["Encoding": encoding])
     }
 }
+
+// MARK: -
+
+extension CSVWriter {
+    @available(*, deprecated, renamed: "encode(rows:configuration:)")
+    public static func serialize<S:Sequence,C:Collection>(rows: S, configuration: Configuration = .init()) throws -> Data where S.Element==C, C.Element==String {
+        try self.encode(rows: rows, configuration: configuration)
+    }
+    
+    @available(*, deprecated, renamed: "encode(rows:into:configuration:)")
+    @inlinable public static func serialize<S:Sequence,C:Collection>(rows: S, into type: String.Type, configuration: Configuration = .init()) throws -> String where S.Element==C, C.Element==String {
+        try self.encode(rows: rows, into: type, configuration: configuration)
+    }
+    
+    @available(*, deprecated, renamed: "encode(rows:into:configuration:)")
+    public static func serialize<S:Sequence,C:Collection>(rows: S, into fileURL: URL, append: Bool, configuration: Configuration = .init()) throws where S.Element==C, C.Element==String {
+        try self.encode(rows: rows, into: fileURL, append: append, configuration: configuration)
+    }
+    
+    @available(*, deprecated, renamed: "encode(rows:setter:)")
+    public static func serialize<S:Sequence,C:Collection>(rows: S, setter: (_ configuration: inout Configuration) -> Void) throws -> Data where S.Element==C, C.Element==String {
+        try self.encode(rows: rows, setter: setter)
+    }
+    
+    @available(*, deprecated, renamed: "encode(rows:into:setter:)")
+    public static func serialize<S:Sequence,C:Collection>(rows: S, into type: String.Type, setter: (_ configuration: inout Configuration) -> Void) throws -> String where S.Element==C, C.Element==String {
+        try self.encode(rows: rows, into: type, setter: setter)
+    }
+    
+    @available(*, deprecated, renamed: "encode(rows:into:append:setter:)")
+    public static func serialize<S:Sequence,C:Collection>(row: S, into fileURL: URL, append: Bool, setter: (_ configuration: inout Configuration) -> Void) throws where S.Element==C, C.Element==String {
+        try self.encode(rows: row, into: fileURL, append: append, setter: setter)
+    }
+}

sources/Codable/Decodable/Decoder.swift

@@ -31,22 +31,22 @@ import Foundation
 }
 
 extension CSVDecoder {
-    /// Returns a value of the type you specify, decoded from a CSV file (given as a `String`).
+    /// Returns a value of the type you specify, decoded from a CSV file (given as a `Data` blob).
     /// - parameter type: The type of the value to decode from the supplied file.
-    /// - parameter string: A Swift string representing a CSV file.
+    /// - parameter data: The data blob representing a CSV file.
     /// - throws: `DecodingError`, or `CSVError<CSVReader>`, or the error raised by your custom types.
-    open func decode<T:Decodable>(_ type: T.Type, from string: String) throws -> T {
-        let reader = try CSVReader(input: string, configuration: self.configuration.readerConfiguration)
+    open func decode<T:Decodable>(_ type: T.Type, from data: Data) throws -> T {
+        let reader = try CSVReader(input: data, configuration: self.configuration.readerConfiguration)
         let source = ShadowDecoder.Source(reader: reader, configuration: self.configuration, userInfo: self.userInfo)
         return try T(from: ShadowDecoder(source: source, codingPath: []))
     }
-
-    /// Returns a value of the type you specify, decoded from a CSV file (given as a `Data` blob).
+    
+    /// Returns a value of the type you specify, decoded from a CSV file (given as a `String`).
     /// - parameter type: The type of the value to decode from the supplied file.
-    /// - parameter data: The data blob representing a CSV file.
+    /// - parameter string: A Swift string representing a CSV file.
     /// - throws: `DecodingError`, or `CSVError<CSVReader>`, or the error raised by your custom types.
-    open func decode<T:Decodable>(_ type: T.Type, from data: Data) throws -> T {
-        let reader = try CSVReader(input: data, configuration: self.configuration.readerConfiguration)
+    open func decode<T:Decodable>(_ type: T.Type, from string: String) throws -> T {
+        let reader = try CSVReader(input: string, configuration: self.configuration.readerConfiguration)
         let source = ShadowDecoder.Source(reader: reader, configuration: self.configuration, userInfo: self.userInfo)
         return try T(from: ShadowDecoder(source: source, codingPath: []))
     }

sources/Codable/Encodable/Containers/EncodingKeyed.swift

@@ -36,23 +36,15 @@ extension ShadowEncoder.KeyedContainer {
 }
 
 extension ShadowEncoder.KeyedContainer {
-    mutating func encodeNil(forKey key: Key) throws {
-        fatalError()
-    }
-    
-    mutating func encode(_ value: Bool, forKey key: Key) throws {
-        fatalError()
-    }
-    
     mutating func encode(_ value: String, forKey key: Key) throws {
         fatalError()
     }
 
-    mutating func encode(_ value: Double, forKey key: Key) throws {
+    mutating func encodeNil(forKey key: Key) throws {
         fatalError()
     }
 
-    mutating func encode(_ value: Float, forKey key: Key) throws {
+    mutating func encode(_ value: Bool, forKey key: Key) throws {
         fatalError()
     }
 
@@ -96,7 +88,81 @@ extension ShadowEncoder.KeyedContainer {
         fatalError()
     }
 
-    mutating func encode<T>(_ value: T, forKey key: Key) throws where T : Encodable {
+    mutating func encode(_ value: Float, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encode(_ value: Double, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encode<T>(_ value: T, forKey key: Key) throws where T:Encodable {
+        fatalError()
+    }
+    
+    mutating func encodeConditional<T>(_ object: T, forKey key: Key) throws where T:AnyObject, T:Encodable {
+        fatalError()
+    }
+}
+
+extension ShadowEncoder.KeyedContainer {
+    mutating func encodeIfPresent(_ value: String?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: Bool?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: Double?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: Float?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: Int?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: Int8?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: Int16?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: Int32?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: Int64?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: UInt?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: UInt8?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: UInt16?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: UInt32?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent(_ value: UInt64?, forKey key: Key) throws {
+        fatalError()
+    }
+    
+    mutating func encodeIfPresent<T>(_ value: T?, forKey key: Key) throws where T:Encodable {
         fatalError()
     }
 }