Crate hedl_csv 

CSV file ↔ HEDL format bidirectional conversion.

This crate provides functionality to convert between CSV files and HEDL documents. It handles both reading CSV data into HEDL structures and writing HEDL data to CSV format.

Features

• Bidirectional conversion: Convert HEDL → CSV and CSV → HEDL
• Type inference: Automatically infer types when reading CSV (null, bool, int, float, string, references)
• Configurable: Support for custom delimiters, quote styles, and header options
• Matrix lists: CSV tables map naturally to HEDL matrix lists
• Error handling: Comprehensive error reporting with context

Examples

Converting HEDL to CSV

use hedl_core::{Document, Item, MatrixList, Node, Value};
use hedl_csv::to_csv;

let mut doc = Document::new((1, 0));
let mut list = MatrixList::new("Person", vec!["name".to_string(), "age".to_string()]);

list.add_row(Node::new(
    "Person",
    "1",
    vec![Value::String("Alice".to_string()), Value::Int(30)],
));

doc.root.insert("people".to_string(), Item::List(list));

let csv_string = to_csv(&doc).unwrap();
println!("{}", csv_string);
// Output:
// id,name,age
// 1,Alice,30

Converting CSV to HEDL

use hedl_csv::from_csv;

let csv_data = r#"
id,name,age,active
1,Alice,30,true
2,Bob,25,false
"#;

let doc = from_csv(csv_data, "Person", &["name", "age", "active"]).unwrap();

// Access the matrix list
let item = doc.get("persons").unwrap();
let list = item.as_list().unwrap();
assert_eq!(list.rows.len(), 2);

Custom Configuration

use hedl_csv::{from_csv_with_config, to_csv_with_config, FromCsvConfig, ToCsvConfig};

// Reading CSV with custom delimiter
let csv_data = "id\tname\tage\n1\tAlice\t30";
let config = FromCsvConfig {
    delimiter: b'\t',
    has_headers: true,
    trim: true,
    ..Default::default()
};
let doc = from_csv_with_config(csv_data, "Person", &["name", "age"], config).unwrap();

// Writing CSV without headers
let config = ToCsvConfig {
    include_headers: false,
    ..Default::default()
};
let csv_string = to_csv_with_config(&doc, config).unwrap();

Custom List Keys (Irregular Plurals)

use hedl_csv::{from_csv_with_config, FromCsvConfig};

let csv_data = "id,name,age\n1,Alice,30\n2,Bob,25";

// Use "people" instead of default "persons" for Person type
let config = FromCsvConfig {
    list_key: Some("people".to_string()),
    ..Default::default()
};
let doc = from_csv_with_config(csv_data, "Person", &["name", "age"], config).unwrap();

// Access using the custom plural form
let list = doc.get("people").unwrap().as_list().unwrap();
assert_eq!(list.rows.len(), 2);

Selective List Export

When a document contains multiple lists, you can export each one independently without converting the entire document:

use hedl_core::Document;
use hedl_csv::to_csv_list;

let doc = Document::new((1, 0));
// Export only the "people" list
let csv_people = to_csv_list(&doc, "people").unwrap();
// Export only the "items" list
let csv_items = to_csv_list(&doc, "items").unwrap();

This is useful when you want to export specific tables from multi-list documents without exporting everything.

Round-trip Conversion

use hedl_csv::{from_csv, to_csv};

let original_csv = "id,name,age\n1,Alice,30\n2,Bob,25\n";
let doc = from_csv(original_csv, "Person", &["name", "age"]).unwrap();
let converted_csv = to_csv(&doc).unwrap();

// The structure is preserved
assert_eq!(original_csv, converted_csv);

Type Inference

When reading CSV data, values are automatically inferred as:

• Empty string or ~ → Value::Null
• true or false → Value::Bool
• Integer pattern → Value::Int
• Float pattern → Value::Float
• @id or @Type:id → Value::Reference
• $(expr) → Value::Expression
• Otherwise → Value::String

Special float values are supported: NaN, Infinity, -Infinity

Structs

FromCsvConfig

Configuration for CSV parsing.

ToCsvConfig

Configuration for CSV output.

Enums

CsvError

CSV conversion error types.

Functions

from_csv

Parse CSV string into a HEDL document with default configuration.

from_csv_reader

Parse CSV from a reader into a HEDL document with default configuration.

from_csv_reader_with_config

Parse CSV from a reader into a HEDL document with custom configuration.

from_csv_with_config

Parse CSV string into a HEDL document with custom configuration.

to_csv

Convert a HEDL document to CSV string.

to_csv_list

Convert a specific matrix list from a HEDL document to CSV string.

to_csv_list_with_config

Convert a specific matrix list from a HEDL document to CSV string with custom configuration.

to_csv_list_writer

Write a specific matrix list to CSV format using a writer.

to_csv_list_writer_with_config

Write a specific matrix list to CSV format with custom configuration.

to_csv_with_config

Convert a HEDL document to CSV string with custom configuration. P1 OPTIMIZATION: Pre-allocate buffer capacity (1.1-1.2x speedup)

to_csv_writer

Write a HEDL document to CSV format using a writer.

to_csv_writer_with_config

Write a HEDL document to CSV format with custom configuration.

Type Aliases

Result

Convenience type alias for Result with CsvError.