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}