Enforce trim characters to not contain delimiter scalars

Author: dehesa

README.md

@@ -142,13 +142,17 @@ A `CSVReadder` parses CSV data from a given input (`String`, or `Data`, or file)
 
     CSV fields are separated within a row with _field delimiters_ (commonly a "comma"). CSV rows are separated through _row delimiters_ (commonly a "line feed"). You can specify any unicode scalar, `String` value, or `nil` for unknown delimiters.
 
+-   `escapingStrategy` (default: `.doubleQuote`) specify the Unicode scalar used to escape fields.
+
+    CSV fields can be escaped in case they contain priviledge characters, such as field/row delimiters. Commonly the escaping character is a double quote (i.e. `"`), by setting this configuration value you can change it (e.g. a single quote), or disable the escaping functionality.
+
 -   `headerStrategy` (default: `.none`) indicates whether the CSV data has a header row or not.
 
     CSV files may contain an optional header row at the very beginning. This configuration value lets you specify whether the file has a header row or not, or whether you want the library to figure it out.
 
 -   `trimStrategy` (default: empty set) trims the given characters at the beginning and end of each parsed field.
 
-    The trim characters are applied for the escaped and unescaped fields.
+    The trim characters are applied for the escaped and unescaped fields. The set cannot include any of the delimiter characters or the escaping scalar. If so, an error will be thrown during initialization.
 
 -   `presample` (default: `false`) indicates whether the CSV data should be completely loaded into memory before parsing begins.
 
@@ -236,6 +240,10 @@ A `CSVWriter` encodes CSV information into a specified target (i.e. a `String`,
 
     CSV fields are separated within a row with _field delimiters_ (commonly a "comma"). CSV rows are separated through _row delimiters_ (commonly a "line feed"). You can specify any unicode scalar, `String` value, or `nil` for unknown delimiters.
 
+-   `escapingStrategy` (default: `.doubleQuote`) specify the Unicode scalar used to escape fields.
+
+    CSV fields can be escaped in case they contain priviledge characters, such as field/row delimiters. Commonly the escaping character is a double quote (i.e. `"`), by setting this configuration value you can change it (e.g. a single quote), or disable the escaping functionality.
+
 -   `headers` (default: `[]`) indicates whether the CSV data has a header row or not.
 
     CSV files may contain an optional header row at the very beginning. If this configuration value is empty, no header row is writen.

Sources/Active/Reader/Reader.swift

@@ -133,6 +133,9 @@ extension CSVReader {
 
 extension CSVReader {
     /// Creates the lookup dictionary from the headers row.
+    ///
+    /// Although it is officially allowed that two CSV headers have the same value, this method will throw an error if that is the case.
+    /// - throws: `CSVError<CSVReader>` exclusively.
     internal func makeHeaderLookup() throws -> [Int:Int] {
         var result: [Int:Int] = .init(minimumCapacity: self.headers.count)
         for (index, header) in self.headers.enumerated() {
@@ -162,13 +165,11 @@ extension CSVReader {
                 case false: result.append(""); break loop
                 }
             }
-            
             // 3. Check for characters to trim before a field is parsed.
             if !self.settings.trimCharacters.isEmpty, self.settings.trimCharacters.contains(scalar) {
                 continue loop
             }
-            
-            // 4. If the unicode scalar retrieved is a double quote, an escaped field is awaiting for parsing.
+            // 4. If the unicode scalar retrieved is the escaping scalar, an escaped field is awaiting parsing.
             if let escapingScalar = self.settings.escapingScalar, scalar == escapingScalar {
                 let field = try self.parseEscapedField(rowIndex: rowIndex, escaping: escapingScalar)
                 result.append(field.value)
@@ -200,26 +201,30 @@ extension CSVReader {
         var field: String.UnicodeScalarView = .init(repeating: starting, count: 1)
         var reachedRowsEnd = false
 
+        // 1. This loop continue parsing a unescaped field till the field end is reached.
         fieldLoop: while true {
-            // Try to retrieve an scalar (if not, it is the EOF).
-            guard let scalar = try self.buffer.next() ?? self.decoder() else { reachedRowsEnd = true; break fieldLoop }
-            // There cannot be double quotes on unescaped fields. If one is encountered, an error is thrown.
+            // 2. Try to retrieve an scalar (if not, it is the EOF).
+            guard let scalar = try self.buffer.next() ?? self.decoder() else {
+                reachedRowsEnd = true
+                break fieldLoop
+            }
+            // 3. A escaping scalar cannot appear on unescaped fields. If one is encountered, an error is thrown.
             if scalar == self.settings.escapingScalar {
                 throw Error.invalidUnescapedField(rowIndex: rowIndex)
-            // If the field delimiter is encountered, return the already parsed characters.
+            // 4. If the field delimiter is encountered, return the already parsed characters.
             } else if try self.isFieldDelimiter(scalar) {
                 reachedRowsEnd = false
                 break fieldLoop
-            // If the row delimiter is encountered, return the already parsed characters.
+            // 5. If the row delimiter is encountered, return the already parsed characters.
             } else if try self.isRowDelimiter(scalar) {
                 reachedRowsEnd = true
                 break fieldLoop
-            // If it is a regular unicode scalar, just store it and continue parsing.
+            // 6. If it is a regular unicode scalar, just store it and continue parsing.
             } else {
                 field.append(scalar)
             }
         }
-        
+        // 7. Once the end has been reached, a field look-back (starting from the end) is performed to check if there are trim characters.
         if !self.settings.trimCharacters.isEmpty {
             while let lastScalar = field.last, self.settings.trimCharacters.contains(lastScalar) {
                 field.removeLast()
@@ -242,13 +247,24 @@ extension CSVReader {
 
         fieldLoop: while true {
             // 1. Retrieve an scalar (if not there, it means EOF). This case is not allowed without closing the escaping field first.
-            guard let scalar = try self.buffer.next() ?? self.decoder() else { throw Error.invalidEOF(rowIndex: rowIndex) }
-            // 2. If the retrieved scalar is not a quote (i.e. "), just store it and continue parsing.
-            guard scalar == escapingScalar else { field.append(scalar); continue fieldLoop }
-            // 3. If the retrieved scalar was a quote, retrieve the following scalar and check if it is EOF. If so, the field has finished and also the row and the file.
-            guard var followingScalar = try self.buffer.next() ?? self.decoder() else { reachedRowsEnd = true; break fieldLoop }
-            // 4. If the second retrieved scalar is another quote, the data is escaping a single quote scalar (quotes are escaped with other quotes).
-            guard followingScalar != escapingScalar else { field.append(escapingScalar); continue fieldLoop }
+            guard let scalar = try self.buffer.next() ?? self.decoder() else {
+                throw Error.invalidEOF(rowIndex: rowIndex)
+            }
+            // 2. If the retrieved scalar is not the escaping scalar, just store it and continue parsing.
+            guard scalar == escapingScalar else {
+                field.append(scalar)
+                continue fieldLoop
+            }
+            // 3. If the retrieved scalar was a escaping scalar, retrieve the following scalar and check if it is EOF. If so, the field has finished and also the row and the file.
+            guard var followingScalar = try self.buffer.next() ?? self.decoder() else {
+                reachedRowsEnd = true
+                break fieldLoop
+            }
+            // 4. If the second retrieved scalar is another escaping scalar, the data is escaping the escaping scalar.
+            guard followingScalar != escapingScalar else {
+                field.append(escapingScalar)
+                continue fieldLoop
+            }
             // 5. Once this point is reached, the field has been properly escaped.
             if !self.settings.trimCharacters.isEmpty {
                 // 6. Trim any character after the quote if necessary.

Sources/Active/Reader/ReaderConfiguration.swift

@@ -5,12 +5,12 @@ extension CSVReader {
     public struct Configuration {
         /// The field and row delimiters.
         public var delimiters: Delimiter.Pair
+        /// The strategy to allow/disable escaped fields and how.
+        public var escapingStrategy: Strategy.Escaping
         /// Indication on whether the CSV will contain a header row or not, or that information is unknown and it should try to be inferred.
         public var headerStrategy: Strategy.Header
         /// Trims the given characters at the beginning and end of each row, and between fields.
         public var trimStrategry: CharacterSet
-        /// The strategy for escaping quoted fields.
-        public var escapingStrategy: Strategy.Escaping
         /// The encoding used to identify the underlying data or `nil` if you want the CSV reader to try to figure it out.
         ///
         /// If no encoding is provided and the input data doesn't contain a Byte Order Marker (BOM), UTF8 is presumed.
@@ -24,9 +24,9 @@ extension CSVReader {
         /// Designated initializer setting the default values.
         public init() {
             self.delimiters = (field: ",", row: "\n")
+            self.escapingStrategy = .doubleQuote
             self.headerStrategy = .none
             self.trimStrategry = .init()
-            self.escapingStrategy = .doubleQuote
             self.encoding = nil
             self.presample = false
         }
@@ -38,10 +38,10 @@ extension CSVReader {
     internal struct Settings {
         /// The unicode scalar delimiters for fields and rows.
         let delimiters: Delimiter.RawPair
-        /// The characters set to be trimmed at the beginning and ending of each field.
-        let trimCharacters: CharacterSet
         /// The unicode scalar used as encapsulator and escaping character (when printed two times).
         let escapingScalar: Unicode.Scalar?
+        /// The characters set to be trimmed at the beginning and ending of each field.
+        let trimCharacters: CharacterSet
 
         /// Creates the inmutable reader settings from the user provided configuration values.
         /// - parameter configuration: The configuration values provided by the API user.
@@ -62,13 +62,21 @@ extension CSVReader {
             case (let delimiter, _):
                 throw Error.invalidDelimiters(delimiter)
             }
-            // 2. Set the trim characters set.
-            self.trimCharacters = configuration.trimStrategry
-            // 3. Set the escaping scalar.
+            // 2. Set the escaping scalar.
             self.escapingScalar = configuration.escapingStrategy.scalar
-            // 4. Ensure trim character set does not include escaping scalar
-            if let escapingScalar = escapingScalar, trimCharacters.contains(escapingScalar) {
-                throw Error.invalidTrimCharacter(escapingScalar: escapingScalar, trimCharacters: trimCharacters)
+            // 3. Set the trim characters set.
+            self.trimCharacters = configuration.trimStrategry
+            // 4. Ensure trim character set doesn't contain the field delimiter.
+            guard delimiters.field.allSatisfy({ !self.trimCharacters.contains($0) }) else {
+                throw Error.invalidTrimCharacters(self.trimCharacters, delimiter: configuration.delimiters.field.rawValue)
+            }
+            // 5. Ensure trim character set doesn't contain the row delimiter.
+            guard delimiters.row.allSatisfy({ !self.trimCharacters.contains($0) }) else {
+                throw Error.invalidTrimCharacters(self.trimCharacters, delimiter: configuration.delimiters.row.rawValue)
+            }
+            // 6. Ensure trim character set does not include escaping scalar
+            if let escapingScalar = self.escapingScalar, self.trimCharacters.contains(escapingScalar) {
+                throw Error.invalidTrimCharacters(self.trimCharacters, escapingScalar: escapingScalar)
             }
         }
     }
@@ -83,10 +91,19 @@ fileprivate extension CSVReader.Error {
               help: "Set different delimiters for field and rows.",
               userInfo: ["Delimiter": delimiter])
     }
-
-    static func invalidTrimCharacter(escapingScalar: Unicode.Scalar, trimCharacters: CharacterSet) -> CSVError<CSVReader> {
+    /// Error raised when a delimiter (whether row or field) is included in the trim character set.
+    static func invalidTrimCharacters(_ trimCharacters: CharacterSet, delimiter: String.UnicodeScalarView) -> CSVError<CSVReader> {
+        .init(.invalidConfiguration,
+              reason: "The trim character set includes delimiter characters.",
+              help: "Remove the delimiter scalars from the trim character set.",
+              userInfo: ["Delimiter": delimiter, "Trim characters": trimCharacters])
+    }
+    /// Error raised when the escaping scalar has been included in the trim character set.
+    /// - parameter escapingScalar: The selected escaping scalar.
+    /// - parameter trimCharacters: The character set selected for trimming.
+    static func invalidTrimCharacters(_ trimCharacters: CharacterSet, escapingScalar: Unicode.Scalar) -> CSVError<CSVReader> {
         .init(.invalidConfiguration,
-              reason: "The trim characters set can not include the escaping scalar.",
+              reason: "The trim characters set includes the escaping scalar.",
               help: "Remove the escaping scalar from the trim characters set.",
               userInfo: ["Escaping scalar": escapingScalar, "Trim characters": trimCharacters])
     }

Sources/Active/Writer/Writer.swift

@@ -177,42 +177,59 @@ extension CSVWriter {
     /// - parameter field: The field to be checked for characters to escape and subsequently written.
     /// - throws: `CSVError<CSVWriter>` exclusively.
     private func lowlevelWrite(field: String) throws {
-        let escapingScalar = self.settings.escapingScalar
         var result: [Unicode.Scalar]
 
+        // 1. If the field is empty, just write two escaping scalars.
         if field.isEmpty {
-            if let escapingScalar = escapingScalar {
-                result = .init(repeating: escapingScalar, count: 2)
-            } else {
-                result = []
+            switch self.settings.escapingScalar {
+            case let s?: result = .init(repeating: s, count: 2)
+            case .none:  result = .init()
             }
+        // 2. If the field contains characters...
         } else {
             let input: [Unicode.Scalar] = .init(field.unicodeScalars)
             result = .init()
-            result.reserveCapacity(input.count + 2)
-            var index = 0
-            var needsEscaping: Unicode.Scalar?
+            // 3. Reserve space for all field scalars plus a bit more in case escaping is needed.
+            result.reserveCapacity(input.count + 3)
 
-            while index < input.endIndex {
-                let scalar = input[index]
-                
-                if scalar == escapingScalar {
-                    needsEscaping = scalar
-                } else if self.isFieldDelimiter(input, &index, &result) || self.isRowDelimiter(input, &index, &result) {
-                    needsEscaping = scalar
-                    continue
+            // 4.A. If escaping is allowed.
+            if let escapingScalar = self.settings.escapingScalar {
+                var (index, needsEscaping) = (0, false)
+                // 5. Iterate through all the input's Unicode scalars.
+                while index < input.endIndex {
+                    let scalar = input[index]
+                    // 6. If the escaping character appears, the field needs escaping, but also the escaping character is duplicated.
+                    if scalar == escapingScalar {
+                        needsEscaping = true
+                        result.append(escapingScalar)
+                    // 7. If there is a field or row delimiter, the field needs escaping.
+                    } else if self.isFieldDelimiter(input, &index, &result) || self.isRowDelimiter(input, &index, &result) {
+                        needsEscaping = true
+                        continue
+                    }
+                    
+                    result.append(scalar)
+                    index += 1
                 }
 
-                index += 1
-                result.append(scalar)
-            }
-            
-            if let needsEscaping = needsEscaping {
-                guard let escapingScalar = escapingScalar else {
-                    throw Error.unescapedDelimiter(needsEscaping)
+                // 8. If the field needed escaping, insert the escaping escalar at the beginning and end of the field.
+                if needsEscaping {
+                    result.insert(escapingScalar, at: result.startIndex)
+                    result.append(escapingScalar)
+                }
+            // 4.B. If escaping is not allowed.
+            } else {
+                var index = 0
+                // 5. Iterate through all the input's Unicode scalars.
+                while index < input.endIndex {
+                    // 6. If the input data contains a delimiter, through an error.
+                    guard !self.isFieldDelimiter(input, &index, &result), !self.isRowDelimiter(input, &index, &result) else {
+                        throw Error.invalidPriviledgeCharacter(on: field)
+                    }
+                    
+                    result.append(input[index])
+                    index += 1
                 }
-                result.insert(escapingScalar, at: result.startIndex)
-                result.append(escapingScalar)
             }
         }
 
@@ -228,11 +245,11 @@ extension CSVWriter {
 }
 
 fileprivate extension CSVWriter.Error {
-    static func unescapedDelimiter(_ delimiter: Unicode.Scalar) -> CSVError<CSVWriter> {
+    static func invalidPriviledgeCharacter(on field: String) -> CSVError<CSVWriter> {
         .init(.invalidInput,
               reason: "A field cannot include a delimiter if escaping strategy is disabled.",
               help: "Remove delimiter from field or set an escaping strategy.",
-              userInfo: ["Invalid character": delimiter])
+              userInfo: ["Field": field])
 
     }
     /// Error raised when the a field is trying to be writen and it overflows the expected number of fields per row.

Sources/Active/Writer/WriterConfiguration.swift

@@ -3,7 +3,7 @@ extension CSVWriter {
     public struct Configuration {
         /// The field and row delimiters.
         public var delimiters: Delimiter.Pair
-        /// The strategy for escaping quoted fields.
+        /// The strategy to allow/disable escaped fields and how.
         public var escapingStrategy: Strategy.Escaping
         /// The row of headers to write at the beginning of the CSV data.
         ///
@@ -53,10 +53,10 @@ extension CSVWriter {
     internal struct Settings {
         /// The unicode scalar delimiters for fields and rows.
         let delimiters: Delimiter.RawPair
-        /// Boolean indicating whether the received CSV contains a header row or not.
-        let headers: [String]
         /// The unicode scalar used as encapsulator and escaping character (when printed two times).
         let escapingScalar: Unicode.Scalar?
+        /// Boolean indicating whether the received CSV contains a header row or not.
+        let headers: [String]
         /// The encoding used to identify the underlying data.
         let encoding: String.Encoding