Skip to main content

csv_spectrum/
lib.rs

1//! CSV parser conformance test corpus.
2//!
3//! This crate ships a fixed set of CSV files that exercise the tricky parts of
4//! CSV parsing, each paired with the JSON its parse result should equal. Feed
5//! every [`Sample::csv`] to your parser and assert the output matches
6//! `Sample::json`, except for `location_coordinates`, whose masked phone field
7//! and lone-object JSON cannot equal a correct parse. The crate parses nothing
8//! itself. It hands you the raw bytes.
9//!
10//! The corpus covers quoting, commas inside quoted fields, escaped (doubled)
11//! quotes, embedded LF and CRLF inside fields, empty quoted fields, multibyte
12//! UTF-8, UTF-8 replacement bytes, and a JSON document stored in one cell.
13//!
14//! # Bytes, not strings
15//!
16//! [`Sample::csv`] and [`Sample::json`] are `&[u8]`. The bytes are returned
17//! exactly as stored. CRLF stays CRLF. The `0xEF 0xBF 0xBD` replacement
18//! sequences in `location_coordinates` stay put. Trailing newlines are kept or
19//! omitted per file. No decoding, no normalization, no trimming.
20//!
21//! # Example
22//!
23//! ```
24//! let samples = csv_spectrum::spectrum();
25//! assert_eq!(samples.len(), 12);
26//! assert_eq!(samples[0].name, "comma_in_quotes");
27//!
28//! // The first sample's quoted field holds a comma that must not split.
29//! let csv = std::str::from_utf8(samples[0].csv).unwrap();
30//! assert!(csv.contains("\"Anytown, WW\""));
31//! ```
32
33#![forbid(unsafe_code)]
34#![warn(missing_docs)]
35
36/// One corpus entry: a CSV input and the JSON its parse result should equal.
37///
38/// `csv` and `json` are raw bytes, stored verbatim. `name` is the shared base
39/// name of the pair with no extension, for example `"comma_in_quotes"`.
40///
41/// [`SAMPLES`] is sorted by unique `name` values. For that table, the derived
42/// `Ord` implementation gives the same order because `name` decides every
43/// comparison.
44#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
45pub struct Sample {
46    /// Base name shared by the CSV and JSON files, extension removed.
47    pub name: &'static str,
48    /// Raw bytes of the CSV input, unparsed.
49    pub csv: &'static [u8],
50    /// Raw bytes of the expected JSON parse result, unparsed.
51    pub json: &'static [u8],
52}
53
54/// Loads a CSV and its matching JSON from `fixtures/` by base name.
55macro_rules! sample {
56    ($name:literal) => {
57        Sample {
58            name: $name,
59            csv: include_bytes!(concat!("../fixtures/csvs/", $name, ".csv")),
60            json: include_bytes!(concat!("../fixtures/json/", $name, ".json")),
61        }
62    };
63}
64
65/// Every sample, in ascending order by name.
66///
67/// The order is fixed and observable. Downstream code may index by position.
68pub const SAMPLES: [Sample; 12] = [
69    sample!("comma_in_quotes"),
70    sample!("empty"),
71    sample!("empty_crlf"),
72    sample!("escaped_quotes"),
73    sample!("json"),
74    sample!("location_coordinates"),
75    sample!("newlines"),
76    sample!("newlines_crlf"),
77    sample!("quotes_and_newlines"),
78    sample!("simple"),
79    sample!("simple_crlf"),
80    sample!("utf8"),
81];
82
83/// Returns all 12 samples, in ascending order by name.
84///
85/// This borrows the static [`SAMPLES`] table. There is no allocation. The
86/// slice supports `.len()`, indexing, `.iter()`, and `for s in spectrum()`.
87///
88/// # Example
89///
90/// ```
91/// let samples = csv_spectrum::spectrum();
92/// let names: Vec<_> = samples.iter().map(|s| s.name).collect();
93/// assert_eq!(names[1], "empty");
94/// ```
95pub fn spectrum() -> &'static [Sample] {
96    &SAMPLES
97}