Unicode scalar encoder added

Author: dehesa

Sources/Active/Reader/ReaderDecoder.swift

@@ -1,7 +1,7 @@
 import Foundation
 
 internal extension CSVReader {
-    /// Function where each time that is executed it generates a new scalar (from the input data), it throws an error, or returns `nil` indicating the end of the file.
+    /// Closure where each time that is executed it generates a new scalar (from the input data), it throws an error, or returns `nil` indicating the end of the file.
     typealias ScalarDecoder = () throws -> Unicode.Scalar?
 
     /// Creates a custom `Unicode.Scalar` iterator wrapping a simple scalar iterator (usually a `String.UnicodeScalarView.Iterator`).

Sources/Active/Writer/Writer.swift

@@ -6,8 +6,8 @@ public final class CSVWriter {
     public let configuration: Configuration
     /// Internal writer settings extracted from the public `configuration` and other values inferred during initialization.
     private let settings: Settings
-//    /// Encoder used to transform unicode scalars into a bunch of bytes.
-//    private let encoder: Unicode.Scalar.Encoder
+    /// Encoder used to transform unicode scalars into a bunch of bytes and store them in the result
+    private let encoder: ScalarEncoder
 //    /// Unicode scalar buffer to keep scalars that hasn't yet been analysed.
 //    private let buffer: ScalarBuffer
 //    /// Check whether the given unicode scalar is part of the field delimiter sequence.
@@ -23,26 +23,28 @@ public final class CSVWriter {
 //    /// The writer state indicating whether it has already begun working or it is idle.
 //    private var state: (file: State.File, row: State.Row)
 
-    init() {
-        fatalError()
+    /// Designated initializer that will set up the CSV writer.
+    ///
+    /// To start "writing", call `beginFile()` after this initializer.
+    /// ```swift
+    /// let writer = try CSVWriter(output: (stream, true), configuration: config, encoder: transformer)
+    /// try writer.beginFile(bom: ..., writeHeaders: true)
+    /// try writer.write(field: "Coco")
+    /// try writer.write(field: "Dog")
+    /// try writer.write(field: "2")
+    /// try writer.endRow()
+    /// try writer.endFile()
+    /// ```
+    /// - parameter output: The output stream on where to write the encoded rows/fields.
+    /// - parameter configuration: The configurations for the CSV writer.
+    /// - parameter encoder: The function transforming unicode scalars into the desired binary representation.
+    /// - throws: `CSVError<CSVWriter>` exclusively.
+    init(configuration: Configuration, encoder: @escaping ScalarEncoder) throws {
+        self.configuration = configuration
+        self.settings = try Settings(configuration: configuration)
+        self.encoder = encoder
     }
 
-//    /// Designated initializer that will set up the CSV writer.
-//    ///
-//    /// To start "writing", call `beginFile()` after this initializer.
-//    /// ```swift
-//    /// let writer = try CSVWriter(output: (stream, true), configuration: config, encoder: transformer)
-//    /// try writer.beginFile(bom: ..., writeHeaders: true)
-//    /// try writer.write(field: "Coco")
-//    /// try writer.write(field: "Dog")
-//    /// try writer.write(field: "2")
-//    /// try writer.endRow()
-//    /// try writer.endFile()
-//    /// ```
-//    /// - parameter output: The output stream on where to write the encoded rows/fields.
-//    /// - parameter configuration: The configurations for the CSV writer.
-//    /// - parameter encoder: The function transforming unicode scalars into the desired binary representation.
-//    /// - throws: `CSVWriter.Error` exclusively.
 //    internal init(output: (stream: OutputStream, closeAtEnd: Bool), configuration: Configuration, encoder: @escaping Unicode.Scalar.Encoder) throws {
 //        self.settings = try Settings(configuration: configuration)
 //

Sources/Active/Writer/WriterAPI.swift

@@ -6,7 +6,14 @@ extension CSVWriter {
     /// - parameter rows: A sequence of rows whose elements are sequences of `String`-like elements.
     /// - parameter configuration: Configuration values specifying how the CSV output should look like.
     /// - throws: `CSVError<CSVWriter>` exclusively.
-    @inlinable public convenience init<S:Sequence,Sub:Sequence>(output type: String.Type, rows: S, configuration: Configuration = .init()) throws where S.Element==Sub, Sub.Element:StringProtocol {
+    public convenience init<S:Sequence,Sub:Sequence>(output type: String.Type, rows: S, configuration: Configuration = .init()) throws where S.Element==Sub, Sub.Element:StringProtocol {
+        let (encoding, bom) = try String.Encoding.selectFrom(provided: configuration.encoding, inferred: nil, serializeBOM: configuration.serializeBOM)
+        
+        let stream = OutputStream(toMemory: ())
+        #warning("Open the stream")
+        
+        let encoder = try CSVWriter.makeEncoder(from: stream, encoding: encoding, firstBytes: bom)
+        let writer = try CSVWriter(configuration: configuration, encoder: encoder)
         fatalError()
     }
 

Sources/Active/Writer/WriterConfiguration.swift

@@ -35,16 +35,12 @@ extension CSVWriter {
         let headers: [String]
         /// The unicode scalar used as encapsulator and escaping character (when printed two times).
         let escapingScalar: Unicode.Scalar = "\""
-        /// The bytes representing the BOM encoding. If empty, no bytes will be written.
-        let bom: [UInt8]
 
         /// Designated initializer taking generic CSV configuration (with possible unknown data) and making it specific to a CSV writer instance.
         /// - parameter configuration: The public CSV writer configuration variables.
         /// - throws: `CSVWriter.Error` exclusively.
-        init(configuration: CSVWriter.Configuration, fileEncoding: String.Encoding?) throws {
-            // 1. Copy headers.
-            self.headers = configuration.headers
-            // 2. Validate the delimiters.
+        init(configuration: CSVWriter.Configuration) throws {
+            // 1. Validate the delimiters.
             let (field, row) = (configuration.delimiters.field.rawValue, configuration.delimiters.row.rawValue)
             if field.isEmpty || row.isEmpty {
                 throw Error.invalidEmptyDelimiter()
@@ -53,41 +49,13 @@ extension CSVWriter {
             } else {
                 self.delimiters = (field, row)
             }
-            // 3. Set up the right BOM.
-            let encoding: String.Encoding
-            switch (configuration.encoding, fileEncoding) {
-            case (let e?, nil): encoding = e
-            case (nil, let e?): encoding = e
-            case (nil, nil): encoding = .utf8
-            case (let lhs?, let rhs?) where lhs == rhs: encoding = lhs
-            case (let lhs?, let rhs?): throw Error.invalidEncoding(provided: lhs, file: rhs)
-            }
-            
-            switch (configuration.serializeBOM, encoding) {
-            case (.always, .utf8): self.bom = BOM.UTF8
-            case (.always, .utf16LittleEndian): self.bom = BOM.UTF16.littleEndian
-            case (.always, .utf16BigEndian),
-                 (.always, .utf16),   (.standard, .utf16),
-                 (.always, .unicode), (.standard, .unicode): self.bom = BOM.UTF16.bigEndian
-            case (.always, .utf32LittleEndian): self.bom = BOM.UTF32.littleEndian
-            case (.always, .utf32BigEndian),
-                 (.always, .utf32),   (.standard, .utf32): self.bom = BOM.UTF32.bigEndian
-            default: self.bom = .init()
-            }
+            // 2. Copy headers.
+            self.headers = configuration.headers
         }
     }
 }
 
 fileprivate extension CSVWriter.Error {
-    /// Error raised when the provided string encoding is different than the inferred file encoding.
-    /// - parameter provided: The string encoding provided by the user.
-    /// - parameter file: The string encoding in the targeted file.
-    static func invalidEncoding(provided: String.Encoding, file: String.Encoding) -> CSVError<CSVWriter> {
-        .init(.invalidConfiguration,
-              reason: "The encoding provided was different than the encoding detected on the file.",
-              help: "Set the configuration encoding to nil or to the file encoding.",
-              userInfo: ["Provided encoding": provided, "File encoding": file])
-    }
     /// Error raised when the the field or/and row delimiters are empty.
     /// - parameter delimiter: The indicated field and row delimiters.
     static func invalidEmptyDelimiter() -> CSVError<CSVWriter> {

Sources/Active/Writer/WriterEncoder.swift

@@ -0,0 +1,148 @@
+import Foundation
+
+internal extension CSVWriter {
+    /// Closure where each time that is executed a scalar will be stored on the final output.
+    typealias ScalarEncoder = (Unicode.Scalar) throws -> Void
+    
+    /// Creates an encoder that take a `Unicode.Scalar` and store the correct byte representation on the appropriate place.
+    /// - parameter stream: Output stream receiving the encoded data.
+    /// - parameter encoding: The string encoding being used for the external representation.
+    /// - parameter firstBytes: Bytes to be preppended at the beggining of the stream.
+    static func makeEncoder(from stream: OutputStream, encoding: String.Encoding, firstBytes: [UInt8]) throws -> ScalarEncoder {
+        if !firstBytes.isEmpty {
+            try CSVWriter.lowlevelWriter(on: stream, bytes: firstBytes, count: firstBytes.count)
+        }
+        
+        switch encoding {
+        case .ascii:
+            return { [unowned stream] (scalar) in
+                guard var byte = Unicode.ASCII.encode(scalar)?.first else { throw Error.invalidASCII(scalar: scalar) }
+                try CSVWriter.lowlevelWriter(on: stream, bytes: &byte, count: 1)
+            }
+        case .utf8:
+            return { [unowned stream] (scalar) in
+                guard let bytes = Unicode.UTF8.encode(scalar),
+                      let _ = try bytes.withContiguousStorageIfAvailable({ try CSVWriter.lowlevelWriter(on: stream, bytes: $0.baseAddress!, count: bytes.count) }) else {
+                    throw Error.invalidUTF8(scalar: scalar)
+                }
+            }
+        case .utf16BigEndian, .utf16, .unicode: // UTF16 & Unicode imply: follow the BOM and if it is not there, assume big endian.
+            return { [unowned stream] (scalar) in
+                guard let tmp = Unicode.UTF16.encode(scalar) else { throw Error.invalidUTF16(scalar: scalar) }
+                let bytes = tmp.flatMap {
+                    [UInt8(truncatingIfNeeded: $0 >> 8),
+                     UInt8(truncatingIfNeeded: $0)]
+                }
+                try CSVWriter.lowlevelWriter(on: stream, bytes: bytes, count: bytes.count)
+            }
+        case .utf16LittleEndian:
+            return { [unowned stream] (scalar) in
+                guard let tmp = Unicode.UTF16.encode(scalar) else { throw Error.invalidUTF16(scalar: scalar) }
+                let bytes = tmp.flatMap {
+                    [UInt8(truncatingIfNeeded: $0),
+                     UInt8(truncatingIfNeeded: $0 >> 8)]
+                }
+                try CSVWriter.lowlevelWriter(on: stream, bytes: bytes, count: bytes.count)
+            }
+        case .utf32BigEndian, .utf32:
+            return { [unowned stream] (scalar) in
+                guard let tmp = Unicode.UTF32.encode(scalar) else { throw Error.invalidUTF32(scalar: scalar) }
+                let bytes = tmp.flatMap {
+                    [UInt8(truncatingIfNeeded: $0 >> 24),
+                     UInt8(truncatingIfNeeded: $0 >> 16),
+                     UInt8(truncatingIfNeeded: $0 >> 8),
+                     UInt8(truncatingIfNeeded: $0)]
+                }
+                try CSVWriter.lowlevelWriter(on: stream, bytes: bytes, count: bytes.count)
+            }
+        case .utf32LittleEndian:
+            return { [unowned stream] (scalar) in
+                guard let tmp = Unicode.UTF32.encode(scalar) else { throw Error.invalidUTF32(scalar: scalar) }
+                let bytes = tmp.flatMap {
+                    [UInt8(truncatingIfNeeded: $0),
+                     UInt8(truncatingIfNeeded: $0 >> 8),
+                     UInt8(truncatingIfNeeded: $0 >> 16),
+                     UInt8(truncatingIfNeeded: $0 >> 24)]
+                }
+                try CSVWriter.lowlevelWriter(on: stream, bytes: bytes, count: bytes.count)
+            }
+        default: throw Error.unsupported(encoding: encoding)
+        }
+    }
+}
+
+fileprivate extension CSVWriter {
+    /// Writes on the stream the given bytes.
+    static func lowlevelWriter(on stream: OutputStream, bytes: UnsafePointer<UInt8>, count: Int, attempts: Int = 2) throws {
+        var (distance, remainingAttempts) = (0, attempts)
+        
+        repeat {
+            let written = stream.write(bytes.advanced(by: distance), maxLength: count - distance)
+            
+            if written > 0 {
+                distance += written
+            } else if written == 0 {
+                remainingAttempts -= 1
+                guard remainingAttempts > 0 else {
+                    throw Error.streamEmptyWrite(underlyingError: stream.streamError, status: stream.streamStatus, numAttempts: attempts)
+                }
+            } else {
+                throw Error.streamFailed(underlyingError: stream.streamError, status: stream.streamStatus)
+            }
+        } while distance < count
+    }
+}
+
+fileprivate extension CSVWriter.Error {
+    /// The given `String.Encoding` is not yet supported by the library.
+    /// - parameter encoding: The desired byte representatoion.
+    static func unsupported(encoding: String.Encoding) -> CSVError<CSVWriter> {
+        .init(.invalidConfiguration,
+              reason: "The given encoding is not yet supported by this library",
+              help: "Contact the library maintainer",
+              userInfo: ["Encoding": encoding])
+    }
+    /// Error raised when a Unicode scalar is an invalid ASCII character.
+    /// - parameter byte: The byte being decoded from the input data.
+    static func invalidASCII(scalar: Unicode.Scalar) -> CSVError<CSVReader> {
+        .init(.invalidInput,
+              reason: "The Unicode Scalar is not an ASCII character.",
+              help: "Make sure the CSV only contains ASCII characters or select a different encoding (e.g. UTF8).",
+              userInfo: ["Unicode scalar": scalar])
+    }
+    /// Error raised when a UTF8 character cannot be constructed from a Unicode scalar value.
+    static func invalidUTF8(scalar: Unicode.Scalar) -> CSVError<CSVReader> {
+        .init(.invalidInput,
+              reason: "The Unicode Scalar couldn't be decoded as UTF8 characters",
+              help: "Make sure the CSV only contains UTF8 characters or select a different encoding.",
+              userInfo: ["Unicode scalar": scalar])
+    }
+    /// Error raised when a UTF16 character cannot be constructed from a Unicode scalar value.
+    static func invalidUTF16(scalar: Unicode.Scalar) -> CSVError<CSVReader> {
+        .init(.invalidInput,
+              reason: "The Unicode Scalar couldn't be decoded as multibyte UTF16",
+              help: "Make sure the CSV only contains UTF16 characters.",
+              userInfo: ["Unicode scalar": scalar])
+    }
+    /// Error raised when a UTF32 character cannot be constructed from a Unicode scalar value.
+    static func invalidUTF32(scalar: Unicode.Scalar) -> CSVError<CSVReader> {
+        .init(.invalidInput,
+              reason: "The Unicode Scalar couldn't be decoded as multibyte UTF32",
+              help: "Make sure the CSV only contains UTF32 characters.",
+              userInfo: ["Unicode scalar": scalar])
+    }
+    ///
+    static func streamFailed(underlyingError: Swift.Error?, status: Stream.Status) -> CSVError<CSVWriter> {
+        .init(.streamFailure, underlying: underlyingError,
+              reason: "The output stream encountered an error while trying to write encoded bytes",
+              help: "Review the underlying error and make sure you have access to the output data (if it is a file)",
+              userInfo: ["Status": status])
+    }
+    ///
+    static func streamEmptyWrite(underlyingError: Swift.Error?, status: Stream.Status, numAttempts: Int) -> CSVError<CSVWriter> {
+        .init(.streamFailure, underlying: underlyingError,
+              reason: "Several attempts were made to write on the stream, but they were unsuccessful.",
+              help: "Review the underlying error (if any) and try again.",
+              userInfo: ["Status": status, "Attempts": numAttempts])
+    }
+}