Oak CSV Parser

High-performance incremental CSV parser for the oak ecosystem with flexible configuration, optimized for data processing and analysis.

🎯 Overview

Oak-csv is a robust parser for CSV, designed to handle complete CSV syntax including modern features. Built on the solid foundation of oak-core, it provides both high-level convenience and detailed AST generation for data processing and analysis.

✨ Features

Complete CSV Syntax: Supports all CSV features including modern specifications
Full AST Generation: Generates comprehensive Abstract Syntax Trees
Lexer Support: Built-in tokenization with proper span information
Error Recovery: Graceful handling of syntax errors with detailed diagnostics

🚀 Quick Start

Basic example:

use oak_csv::CsvParser;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let parser = CsvParser::new();
    let csv_content = r#"
name,age,city,country
John Doe,25,New York,USA
Jane Smith,30,London,UK
Bob Johnson,35,Paris,France
    "#;
    
    let document = parser.parse_document(csv_content)?;
    println!("Parsed CSV document with {} records.", document.records.len());
    Ok(())
}

📋 Parsing Examples

Document Parsing

use oak_csv::{CsvParser, ast::Document};

let parser = CsvParser::new();
let csv_content = r#"
product_id,product_name,price,stock
001,Smartphone,599.99,50
002,Laptop,1299.99,25
003,Headphones,199.99,100
"#;

let document = parser.parse_document(csv_content)?;
println!("Headers: {:?}", document.headers);
println!("Records: {}", document.records.len());

Record Parsing

use oak_csv::{CsvParser, ast::Record};

let parser = CsvParser::new();
let csv_content = "Alice,28,Engineer,Seattle";

let record = parser.parse_record(csv_content)?;
println!("Fields: {:?}", record.fields);
println!("Field count: {}", record.fields.len());

Field Parsing

use oak_csv::{CsvParser, ast::Field};

let parser = CsvParser::new();
let field_content = "\"John \"JD\" Doe\"";

let field = parser.parse_field(field_content)?;
println!("Field value: {}", field.value);
println!("Quoted: {}", field.is_quoted);

🔧 Advanced Features

Token-Level Parsing

use oak_csv::{CsvParser, lexer::Token};

let parser = CsvParser::new();
let tokens = parser.tokenize("name,age,city\nJohn,25,NYC")?;
for token in tokens {
    println!("{:?}", token.kind);
}

Error Handling

use oak_csv::CsvParser;

let parser = CsvParser::new();
let invalid_csv = r#"
name,age,city
John,25,NYC
Jane,30  // Missing field
Bob,35,London,UK
"#;

match parser.parse_document(invalid_csv) {
    Ok(document) => println!("Parsed CSV document successfully."),
    Err(e) => {
        println!("Parse error at line {} column {}: {}", 
            e.line(), e.column(), e.message());
        if let Some(context) = e.context() {
            println!("Error context: {}", context);
        }
    }
}

🏗️ AST Structure

The parser generates a comprehensive AST with the following main structures:

Document: Root container for CSV documents
Record: CSV records with field values
Field: Individual CSV fields with optional quoting
Header: Optional header row with column names
Delimiter: Field delimiter (usually comma)
Quote: Quote character for quoted fields

📊 Performance

Streaming: Parse large CSV files without loading entirely into memory
Incremental: Re-parse only changed sections
Memory Efficient: Smart AST node allocation
Fast Recovery: Quick error recovery for better IDE integration

🔗 Integration

Oak-csv integrates seamlessly with:

Data Processing: Extract data from CSV files
Configuration Files: Parse CSV configuration files
Data Analysis: Process CSV data for analysis
IDE Support: Language server protocol compatibility
ETL Pipelines: CSV parsing for data transformation

📚 Examples

Check out the examples directory for comprehensive examples:

Complete CSV document parsing
Record and field analysis
Data extraction and transformation
Integration with development workflows

🤝 Contributing

Contributions are welcome!

Please feel free to submit pull requests at the project repository or open issues.

oak-csv 0.0.2