Build Your Own CSV Parser

This challenge is inspired by the need to parse CSV (Comma-Separated Values) files, one of the most common data exchange formats. While CSV appears simple on the surface, handling all edge cases correctly requires careful implementation of parsing logic.

CSV Format Specification

Your parser should handle the standard CSV format as defined in RFC 4180, plus common variations:

1. Basic Structure:

   • Records (rows) separated by line breaks (CRLF, LF, or CR)
   • Fields (columns) separated by delimiters (comma by default)
   • Optional header row with field names

2. Quoted Fields:

   • Fields containing delimiters, quotes, or line breaks must be enclosed in double quotes
   • Embedded quotes are escaped by doubling them ("")
   • Leading/trailing whitespace is preserved inside quotes

3. Edge Cases:

   • Empty fields and empty records
   • Mixed quoted and unquoted fields
   • Different line ending styles
   • Unicode content and different encodings

Supported Features

Your CSV parser should support:

1. Flexible Configuration:

   • Customizable field delimiter (comma, semicolon, tab, pipe, etc.)
   • Configurable quote character (double quote by default)
   • Option to trim whitespace from unquoted fields
   • Header row detection and field naming

2. Multiple Output Formats:

   • Array of arrays (raw data)
   • Array of objects (with field names from header)
   • Stream processing for large files
   • JSON conversion

3. Validation and Error Handling:

   • Syntax error detection with line and column numbers
   • Data type validation and conversion
   • Handling of malformed records

Example Usage

# Basic CSV parsing
csv_content = """
name,age,city
John,25,New York
Jane,30,"San Francisco"
"""

parser = CSVParser()
data = parser.parse(csv_content)
# Result: [{"name": "John", "age": "25", "city": "New York"}, ...]

# Custom delimiter and configuration
parser = CSVParser(delimiter=';', has_header=True, trim_whitespace=True)
data = parser.parse_file('data.csv')

# Streaming for large files
parser = CSVParser()
for record in parser.parse_stream('large_file.csv'):
    process_record(record)