CodableCSV

CodableCSV provides two primary ways to interact with CSV data:

1. Imperative Reader/Writer: Use this for low-level, row-by-row, and field-by-field processing. This is useful when you need fine-grained control over the parsing or writing process.
2. Declarative Decoder/Encoder: Use this to leverage Swift's Codable protocol. This allows you to map CSV rows directly to Swift structs or classes, providing a high-level, type-safe interface.

By default, CSVDecoder matches Codable property names to the CSV header row. If your CSV does not have a header row, or if you want to improve performance, you can use integer-based CodingKeys to map properties directly to field indices. This allows the decoder to skip the string-matching step.

struct Student: Codable {
    var name: String
    var age: Int
    var hasPet: Bool

    private enum CodingKeys: Int, CodingKey {
        case name = 0
        case age = 1
        case hasPet = 2
    }
}

To learn how to use CodableCSV, consult the following resources:

• README.md: The primary source of information, covering everything from basic usage to performance optimization tips. Look for the right-pointing carets (▶) to expand detailed sections.
• GitHub Issues: Search for existing questions by looking for issues labeled with question.
• New Questions: If you cannot find an answer, you can create a new issue on GitHub and label it as question.

You can integrate CodableCSV into your Swift project using either Swift Package Manager (SPM) or CocoaPods.

Swift Package Manager (SPM)

Add the dependency to your Package.swift file:

CocoaPods

Add the following line to your Podfile:

// swift-tools-version:5.1
import PackageDescription

let package = Package(
    /* Your package name, supported platforms, and generated products go here */
    dependencies: [
        .package(url: "https://github.com/dehesa/CodableCSV.git", from: "0.6.7")
    ],
    targets: [
        .target(name: /* Your target name here */, dependencies: ["CodableCSV"])
    ]
)

pod 'CodableCSV', '~> 0.6.7'

Since CodableCSV relies on Swift's Codable protocol, you may need to understand how encoding and decoding custom types work. Recommended resources include:

• Apple's Documentation: Official guides on encoding and decoding custom types.
• Flight School: The 'Guide to Swift Codable' by Mattt.
• Swift Forums: For complex queries, visit the Swift forums (specifically the 'Using Swift' category) and use the codable search tag.
• CodableCSV README: Contains specific usage examples related to CSV serialization.

To use the library in your Swift files, import the module:

import CodableCSV

You can configure a CSVReader during initialization using a closure. Available properties include:

• encoding: The String.Encoding (e.g., .utf8). If nil, it attempts to detect via BOM, defaulting to .utf8.
• delimiters: A tuple specifying field and row delimiters (e.g., (field: ",", row: "\n")).
• escapingStrategy: The Unicode scalar used to escape fields (default is "").
• headerStrategy: Determines how headers are handled (e.g., .firstLine or .none).
• trimStrategy: A set of characters to trim from the start and end of parsed fields.
• presample: If true, the entire CSV is loaded into memory before parsing begins.

let reader = CSVReader(input: ...) {
    $0.encoding = .utf8
    $0.delimiters.row = "\r\n"
    $0.headerStrategy = .firstLine
    $0.trimStrategy = .whitespaces
}

You can configure a CSVWriter during initialization using a closure. Available properties include:

• delimiters: A tuple specifying field and row delimiters.
• escapingStrategy: The Unicode scalar used to escape fields (default is .doubleQuote).
• headers: An array of strings to be written as the first row.
• encoding: The String.Encoding for the output.
• bomStrategy: Determines if a Byte Order Marker is included (.always, .never, or .convention).

let writer = CSVWriter(fileURL: url) {
    $0.delimiters.row = "\r\n"
    $0.headers = ["Name", "Age", "Pet"]
    $0.encoding = .utf8
    $0.bomStrategy = .never
}

Imperative operations in CodableCSV throw CSVError. This error type provides detailed diagnostic information to help resolve issues like invalid configuration or malformed CSV data.

Key properties of CSVError include:

• type: The error category.
• failureReason: A description of what went wrong.
• helpAnchor: Advice on how to fix the error.
• errorUserInfo: Associated arguments.
• underlyingError: The original error that caused the failure, if applicable.
• localizedDescription: A human-readable error string.

do {
    let writer = try CSVWriter()
    try writer.write(row: ["data"])
    try writer.endEncoding()
} catch let error as CSVError {
    print("Reason: \(error.failureReason)")
    print("Help: \(error.helpAnchor)")
}

To ensure your CSV headers match your Swift model, you can use CaseIterable on a String-based CodingKeys enum to automatically populate the encoder's headers configuration.

struct Student: Codable {
    var name: String
    var age: Int
    var hasPet: Bool

    enum CodingKeys: String, CodingKey, CaseIterable {
        case name, age, hasPet
    }
}

let encoder = CSVEncoder {
    $0.headers = Student.CodingKeys.allCases.map { $0.rawValue }
}