CSVWriter overhaul

Author: dehesa

README.md

@@ -36,39 +36,39 @@ The _active entities_ provide imperative control on how to read or write CSV dat
 <ul>
 <details><summary><code>CSVReader</code>.</summary><p>
 
-A `CSVReadder` parses CSV data from an input and returns CSV row as an array of strings.
+A `CSVReadder` parses CSV data from a given input (`String`, or `Data`, or file) and returns CSV rows as a `String`s array. `CSVReader` can be used at a "high-level", in which case it parses an input completely; or at a lower level, in which each row is decoded when requested.
+
+-   Complete input parsing.
+
+    ```swift
+    let file = try CSVReader.parse(input: ...)
+    // file is of type: CSVReader.Output
+    ```
+
+    This type of parsing returns a simple structure containing the CSV headers and CSV rows. Additionally it lets you access each field through the header name or the field index.
 
 -   Row-by-row parsing.
 
     ```swift
-    let reader = try CSVReader(data: ...)
+    let reader = try CSVReader(input: "...")
     while let row = try reader.parseRow() {
         // Do something with the row: [String]
     }
     ```
 
-    Alternatively you can use the `parseRecord()` function which also returns the next CSV row, but it wraps the result in a convenience structure. This structure lets you access each field with the header name (as long as the `headerStrategy` is market with `.firstLine`).
+    Alternatively you can use the `parseRecord()` function which also returns the next CSV row, but it wraps the result in a convenience structure. This structure lets you access each field with the header name (as long as the `headerStrategy` is marked with `.firstLine`).
 
 -   `Sequence` syntax parsing.
 
     ```swift
-    let reader = try CSVReader(fileURL: ...)
+    let reader = try CSVReader(input: URL(...), configuration: ...)
     for row in reader {
         // Do something with the row: [String]
     }
     ```
 
     Please note the `Sequence` syntax (i.e. `IteratorProtocol`) doesn't throw errors; therefore if the CSV data is invalid, the previous code will crash. If you don't control the CSV data origin, use `parseRow()` instead.
 
--   Whole input parsing.
-
-    ```swift
-    let file = try CSVReader.parse(string: ..., configuration: ...)
-    // file is of type: CSVReader.Output
-    ```
-
-    This type of parsing returns a simple structure containing the CSV headers and CSV rows. Additionally it lets you access each field through the header name or the field index.
-
 ### Reader Configuration
 
 `CSVReader` accepts the following configuration properties:
@@ -96,7 +96,7 @@ A `CSVReadder` parses CSV data from an input and returns CSV row as an array of
 The configuration values are set during initialization and can be passed to the `CSVReader` instance through a structure or with a convenience closure syntax:
 
 ```swift
-let reader = CSVReader(data: ...) {
+let reader = CSVReader(input: ...) {
     $0.encoding = .utf8
     $0.delimiters.row = "\r\n"
     $0.headerStrategy = .firstLine
@@ -108,6 +108,31 @@ let reader = CSVReader(data: ...) {
 
 <details><summary><code>CSVWriter</code>.</summary><p>
 
+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 lower level, in which case rows or fields can be writen individually.
+
+-   Full encoding.
+
+    ```swift
+    let data = try CSVWriter.serialize(rows: [...], into: Data.self)
+    ```
+
+-   Row-by-row encoding.
+
+    ```swift
+    let writer = try CSVWriter()
+    for row in customData {
+        try writer.write(row: row)
+    }
+    let outcome = writer.data()
+    ```
+
+-   Field-by-field encoding.
+
+    ```swift
+    let writer = try CSVWriter(fileURL: ...)
+    try writer.write(field: ...)
+    ```
+
 #warning("TODO:")
 
 </p></details>

Sources/Active/Reader/Reader.swift

@@ -46,7 +46,7 @@ public final class CSVReader: IteratorProtocol, Sequence {
         self.isFieldDelimiter = CSVReader.makeMatcher(delimiter: self.settings.delimiters.field, buffer: self.buffer, decoder: self.decoder)
         self.isRowDelimiter = CSVReader.makeMatcher(delimiter: self.settings.delimiters.row, buffer: self.buffer, decoder: self.decoder)
         self.count = (0, 0)
-        self.status = .reading
+        self.status = .active
 
         switch configuration.headerStrategy {
         case .none: break
@@ -55,8 +55,7 @@ public final class CSVReader: IteratorProtocol, Sequence {
             guard !headers.isEmpty else { throw Error.invalidEmptyHeader() }
             self.headers = headers
             self.count = (rows: 1, fields: headers.count)
-//        case .unknown:
-//            #warning("TODO:")
+//        case .unknown: #warning("TODO")
         }
     }
 }
@@ -96,7 +95,7 @@ extension CSVReader {
     /// - returns: The row's fields or `nil` if there isn't anything else to parse. The row will never be an empty array.
     public func parseRow() throws -> [String]? {
         switch self.status {
-        case .reading: break
+        case .active: break
         case .finished: return nil
         case .failed(let e): throw e
         }
@@ -126,6 +125,8 @@ extension CSVReader {
     }
 }
 
+// MARK: -
+
 extension CSVReader {
     /// Creates the lookup dictionary from the headers row.
     internal func makeHeaderLookup() throws -> [Int:Int] {
@@ -268,6 +269,8 @@ extension CSVReader {
     }
 }
 
+// MARK: -
+
 fileprivate extension CSVReader.Error {
     /// Error raised when a header was required, but the line was empty.
     static func invalidEmptyHeader() -> CSVError<CSVReader> {

Sources/Active/Reader/ReaderAPI.swift

@@ -6,6 +6,7 @@ extension CSVReader {
     /// - parameter configuration: Recipe detailing how to parse the CSV data (i.e. encoding, delimiters, etc.).
     /// - throws: `CSVError<CSVReader>` exclusively.
     @_specialize(exported: true, where S==String)
+    @_specialize(exported: true, where S==Substring)
     public convenience init<S>(input: S, configuration: Configuration = .init()) throws where S:StringProtocol {
         let buffer = ScalarBuffer(reservingCapacity: 8)
         let decoder = CSVReader.makeDecoder(from: input.unicodeScalars.makeIterator())
@@ -30,7 +31,7 @@ extension CSVReader {
             var dataIterator = input.makeIterator()
             let (inferredEncoding, unusedBytes) = String.Encoding.infer(from: &dataIterator)
             // B.2. Select the appropriate encoding depending from the user provided encoding (if any), and the BOM encoding (if any).
-            let encoding = try String.Encoding.selectFrom(provided: configuration.encoding, inferred: inferredEncoding)
+            let encoding = try CSVReader.selectEncodingFrom(provided: configuration.encoding, inferred: inferredEncoding)
             // B.3. Create the scalar iterator producing all `Unicode.Scalar`s from the data bytes.
             let decoder = try CSVReader.makeDecoder(from: dataIterator, encoding: encoding, firstBytes: unusedBytes)
             try self.init(configuration: configuration, buffer: buffer, decoder: decoder)
@@ -59,7 +60,7 @@ extension CSVReader {
                 // B.2. Check whether the input data has a BOM.
                 let inferred = try String.Encoding.infer(from: stream)
                 // B.3. Select the appropriate encoding depending from the user provided encoding (if any), and the BOM encoding (if any).
-                encoding = try String.Encoding.selectFrom(provided: configuration.encoding, inferred: inferred.encoding)
+                encoding = try CSVReader.selectEncodingFrom(provided: configuration.encoding, inferred: inferred.encoding)
                 unusedBytes = inferred.unusedBytes
             } catch let error {
                 if stream.streamStatus != .closed { stream.close() }
@@ -118,6 +119,7 @@ extension CSVReader {
     /// - throws: `CSVError<CSVReader>` exclusively.
     /// - returns: Tuple with the CSV headers (empty if none) and all records within the CSV file.
     @_specialize(exported: true, where S==String)
+    @_specialize(exported: true, where S==Substring)
     public static func parse<S>(input: S, configuration: Configuration = .init()) throws -> Output where S:StringProtocol {
         let reader = try CSVReader(input: input, configuration: configuration)
         let lookup = try reader.makeHeaderLookup()

Sources/Active/Reader/ReaderBuffer.swift

@@ -0,0 +1,45 @@
+extension CSVReader {
+    /// Buffer used to stored previously read unicode scalars.
+    internal final class ScalarBuffer: IteratorProtocol {
+        /// Unicode scalars read inferring configuration variables that were unknown.
+        ///
+        /// This buffer is reversed to make it efficient to remove elements.
+        private var readScalars: [Unicode.Scalar]
+        
+        /// Creates the buffer with a given capacity value.
+        init(reservingCapacity capacity: Int) {
+            self.readScalars = []
+            self.readScalars.reserveCapacity(capacity)
+        }
+        
+        func next() -> Unicode.Scalar? {
+            guard !self.readScalars.isEmpty else { return nil }
+            return self.readScalars.removeLast()
+        }
+        
+        /// Inserts a single unicode scalar at the beginning of the buffer.
+        func preppend(scalar: Unicode.Scalar) {
+            self.readScalars.append(scalar)
+        }
+        
+        /// Inserts a sequence of scalars at the beginning of the buffer.
+        func preppend<S:Sequence>(scalars: S) where S.Element == Unicode.Scalar {
+            self.readScalars.append(contentsOf: scalars.reversed())
+        }
+        
+        /// Appends a single unicode scalar to the buffer.
+        func append(scalar: Unicode.Scalar) {
+            self.readScalars.insert(scalar, at: self.readScalars.startIndex)
+        }
+        
+        /// Appends a sequence of unicode scalars to the buffer.
+        func append<S:Sequence>(scalars: S) where S.Element == Unicode.Scalar {
+            self.readScalars.insert(contentsOf: scalars.reversed(), at: self.readScalars.startIndex)
+        }
+        
+        /// Removes all scalars in the buffer.
+        func removeAll() {
+            self.readScalars.removeAll()
+        }
+    }
+}

Sources/Active/Reader/ReaderConfiguration.swift

@@ -55,7 +55,7 @@ extension CSVReader {
             case (let field, nil):
                 self.delimiters = try CSVReader.inferRowDelimiter(fieldDelimiter: field, decoder: decoder, buffer: buffer)
             case (let field, let row) where !field.elementsEqual(row):
-                self.delimiters = (field, row)
+                self.delimiters = (.init(field), .init(row))
             case (let delimiter, _):
                 throw Error.invalidDelimiters(delimiter)
             }

Sources/Active/Reader/ReaderDecoder.swift

@@ -345,7 +345,7 @@ fileprivate extension CSVReader.Error {
         .init(.streamFailure, underlying: underlyingError,
               reason: "The input stream encountered an error while trying to read input bytes.",
               help: "Review the internal error and make sure you have access to the input data.",
-              userInfo: ["Status": status])
+              userInfo: ["Stream status": status])
     }
     /// Error raised when trying to retrieve two bytes from the input data, but only one was available.
     static func incompleteUTF16() -> CSVError<CSVReader> {

Sources/Active/Reader/ReaderEncodings.swift

@@ -36,13 +36,15 @@ internal extension String.Encoding {
         assert(unusedBytes != nil)
         return (encoding, unusedBytes!)
     }
-    
+}
+
+internal extension CSVReader {
     /// Select the appropriate encoding depending on the `String` encoding provided by the user and the encoding inferred from the Byte Order Marker.
     /// - parameter provided: The user provided `String` encoding.
     /// - parameter inferred: The `String` encoding inferred from the data Byte Order Marker.
     /// - throws: `CSVError<CSVReader>` exclusively.
     /// - returns: The appropriate `String.Encoding` matching from the provided and inferred values.
-    static func selectFrom(provided: String.Encoding?, inferred: String.Encoding?) throws -> String.Encoding {
+    static func selectEncodingFrom(provided: String.Encoding?, inferred: String.Encoding?) throws -> String.Encoding {
         switch (provided, inferred) {
         case (nil, nil): return .utf8
         case (nil, let rhs?): return rhs

Sources/Active/Reader/ReaderInference.swift

@@ -3,20 +3,23 @@ internal extension CSVReader {
     /// - parameter decoder: The instance providing the input `Unicode.Scalar`s.
     /// - throws: `CSVError<CSVReader>` exclusively.
     static func inferFieldDelimiter(rowDelimiter: String.UnicodeScalarView, decoder: ScalarDecoder, buffer: ScalarBuffer) throws -> Delimiter.RawPair {
+        //#warning("TODO:")
         throw Error.unsupportedInference()
     }
 
     /// Tries to infer the row delimiter given the field delimiter.
     /// - parameter decoder: The instance providing the input `Unicode.Scalar`s.
     /// - throws: `CSVError<CSVReader>` exclusively.
     static func inferRowDelimiter(fieldDelimiter: String.UnicodeScalarView, decoder: ScalarDecoder, buffer: ScalarBuffer) throws -> Delimiter.RawPair {
+        //#warning("TODO:")
         throw Error.unsupportedInference()
     }
 
     /// Tries to infer both the field and row delimiter from the raw data.
     /// - parameter decoder: The instance providing the input `Unicode.Scalar`s.
     /// - throws: `CSVError<CSVReader>` exclusively.
     static func inferDelimiters(decoder: ScalarDecoder, buffer: ScalarBuffer) throws -> Delimiter.RawPair {
+        //#warning("TODO:")
         throw Error.unsupportedInference()
     }
 }
@@ -30,22 +33,22 @@ internal extension CSVReader {
     typealias DelimiterChecker = (_ scalar: Unicode.Scalar) throws -> Bool
 
     /// Creates a delimiter identifier closure.
-    /// - parameter view: The unicode characters forming a targeted delimiter.
+    /// - parameter delimiter: The unicode characters forming a targeted delimiter.
     /// - parameter buffer: A unicode character buffer containing further characters to parse.
     /// - parameter decoder: The instance providing the input `Unicode.Scalar`s.
     /// - returns: A closure which given the targeted unicode character and the buffer and iterrator, returns a Boolean indicating whether there is a delimiter.
-    static func makeMatcher(delimiter view: String.UnicodeScalarView, buffer: ScalarBuffer, decoder: @escaping CSVReader.ScalarDecoder) -> CSVReader.DelimiterChecker {
+    static func makeMatcher(delimiter: [Unicode.Scalar], buffer: ScalarBuffer, decoder: @escaping CSVReader.ScalarDecoder) -> CSVReader.DelimiterChecker {
         // This should never be triggered.
-        assert(!view.isEmpty)
+        assert(!delimiter.isEmpty)
 
         // For optimizations sake, a delimiter proofer is built for a single unicode scalar.
-        if view.count == 1 {
-            let delimiter: Unicode.Scalar = view.first!
+        if delimiter.count == 1 {
+            let delimiter: Unicode.Scalar = delimiter.first!
             return { delimiter == $0 }
             // For optimizations sake, a delimiter proofer is built for two unicode scalars.
-        } else if view.count == 2 {
-            let firstDelimiter = view.first!
-            let secondDelimiter = view[view.index(after: view.startIndex)]
+        } else if delimiter.count == 2 {
+            let firstDelimiter = delimiter.first!
+            let secondDelimiter = delimiter[delimiter.index(after: delimiter.startIndex)]
 
             return { [unowned buffer] in
                 guard firstDelimiter == $0, let secondScalar = try buffer.next() ?? decoder() else {
@@ -63,17 +66,17 @@ internal extension CSVReader {
         } else {
             return { [unowned buffer] (firstScalar) -> Bool in
                 var scalar = firstScalar
-                var index = view.startIndex
+                var index = delimiter.startIndex
                 var toIncludeInBuffer: [Unicode.Scalar] = .init()
 
                 while true {
-                    guard scalar == view[index] else {
+                    guard scalar == delimiter[index] else {
                         buffer.preppend(scalars: toIncludeInBuffer)
                         return false
                     }
 
-                    index = view.index(after: index)
-                    guard index < view.endIndex else { return true }
+                    index = delimiter.index(after: index)
+                    guard index < delimiter.endIndex else { return true }
 
                     guard let nextScalar = try buffer.next() ?? decoder() else {
                         buffer.preppend(scalars: toIncludeInBuffer)

Sources/Active/Reader/ReaderInternals.swift

@@ -2,7 +2,7 @@ extension CSVReader {
     /// Reader status indicating whether there are remaning lines to read, the CSV has been completely parsed, or an error occurred and no further operation shall be performed.
     public enum Status {
         /// The CSV file hasn't been completely parsed.
-        case reading
+        case active
         /// There are no more rows to read. The EOF has been reached.
         case finished
         /// An error has occurred and no further operations shall be performed with the reader instance.