//! csv_utils — a CSV parsing library for Zig. //! //! ## Quick start //! //! Streaming row-by-row with no allocation: //! ```zig //! const csv = @import("csv_utils"); //! var field_buf: [4096]u8 = undefined; //! var it = try csv.BoundedRowIterator(csv.default_max_fields) //! .init(reader, &field_buf, .{}); //! while (try it.next()) |row| { //! for (row.fields) |field| { ... } //! } //! ``` //! //! Full parse into memory: //! ```zig //! var table = try csv.parseTable(reader, allocator); //! defer table.deinit(); //! for (table.rows) |row| { ... } //! ``` //! //! ## API layering //! //! ``` //! HeaderTable ← lookup by (row, name); allocates //! └─ Table ← owned 2-D []const u8; allocates //! └─ HeaderIterator ← lookup by name per row; allocates //! └─ RowIterator family — three storage variants: //! - RowIterator (allocating; grows) //! - BoundedRowIterator(N) (comptime stack) //! - FixedBufferRowIterator (caller buffer) //! └─ FieldIterator ← THE state machine //! └─ std.Io.Reader //! ``` const std = @import("std"); const Io = std.Io; const Allocator = std.mem.Allocator; // ── Re-exports ───────────────────────────────────────────────────────────── pub const Dialect = @import("dialect.zig").Dialect; pub const Error = @import("error.zig").Error; pub const FieldIterator = @import("field_iterator.zig").FieldIterator; const row_iterator_mod = @import("row_iterator.zig"); pub const Row = row_iterator_mod.Row; pub const RowIterator = row_iterator_mod.RowIterator; pub const BoundedRowIterator = row_iterator_mod.BoundedRowIterator; pub const FixedBufferRowIterator = row_iterator_mod.FixedBufferRowIterator; pub const default_max_fields = row_iterator_mod.default_max_fields; pub const HeaderIterator = @import("header_iterator.zig").HeaderIterator; pub const Table = @import("table.zig").Table; pub const HeaderTable = @import("header_table.zig").HeaderTable; pub const Writer = @import("writer.zig").Writer; // unimplemented; future feature // ── Convenience wrappers using the default Dialect ───────────────────────── /// Construct a no-allocator `BoundedRowIterator(default_max_fields)` /// over `reader` with the default dialect. The shortest-path entry /// point for "I just want to iterate rows". pub fn rows( reader: *Io.Reader, field_buf: []u8, ) Error!BoundedRowIterator(default_max_fields) { return BoundedRowIterator(default_max_fields).init(reader, field_buf, .{}); } /// Construct an allocating `RowIterator` over `reader` with the /// default dialect. Use when row width may exceed /// `default_max_fields`. pub fn rowsAlloc( reader: *Io.Reader, field_buf: []u8, allocator: Allocator, ) Error!RowIterator { return RowIterator.init(reader, field_buf, allocator, .{}); } /// Construct a `HeaderIterator` with default options. pub fn headerRows( reader: *Io.Reader, field_buf: []u8, allocator: Allocator, ) Error!HeaderIterator { return HeaderIterator.init(reader, field_buf, allocator, .{}); } /// Parse the entire input into a `Table` with the default dialect. pub fn parseTable(reader: *Io.Reader, allocator: Allocator) Error!Table { return Table.parse(reader, allocator, .{}); } /// Parse the entire input into a `HeaderTable` with default options. pub fn parseHeaderTable(reader: *Io.Reader, allocator: Allocator) Error!HeaderTable { return HeaderTable.parse(reader, allocator, .{}); } test { // Pull in every submodule's test block when running `zig build test`. _ = @import("dialect.zig"); _ = @import("error.zig"); _ = @import("field_iterator.zig"); _ = @import("row_iterator.zig"); _ = @import("header_iterator.zig"); _ = @import("table.zig"); _ = @import("header_table.zig"); _ = @import("writer.zig"); } // ── Runnable examples (one per parser tier; N-12) ───────────────────────── const testing = std.testing; test "example: FieldIterator (lowest-level, no allocator)" { var reader = Io.Reader.fixed("a,b\n1,2\n"); var field_buf: [64]u8 = undefined; var it = try FieldIterator.init(&reader, &field_buf, .{}); var n_fields: usize = 0; while (try it.next()) |result| { _ = result.data; _ = result.end_of_row; n_fields += 1; } try testing.expectEqual(@as(usize, 4), n_fields); } test "example: BoundedRowIterator (no allocator, comptime max columns)" { var reader = Io.Reader.fixed("a,b,c\n1,2,3\n"); var field_buf: [256]u8 = undefined; var it = try BoundedRowIterator(64).init(&reader, &field_buf, .{}); var n_rows: usize = 0; while (try it.next()) |row| { try testing.expectEqual(@as(usize, 3), row.count()); n_rows += 1; } try testing.expectEqual(@as(usize, 2), n_rows); } test "example: RowIterator (allocating; unbounded row width)" { var reader = Io.Reader.fixed("a,b,c\n1,2,3\n"); var field_buf: [256]u8 = undefined; var it = try RowIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit(); var n_rows: usize = 0; while (try it.next()) |row| { _ = row; n_rows += 1; } try testing.expectEqual(@as(usize, 2), n_rows); } test "example: HeaderIterator (lookup by header name)" { var reader = Io.Reader.fixed("name,age\nAlice,30\nBob,25\n"); var field_buf: [256]u8 = undefined; var it = try HeaderIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit(); const r1 = (try it.next()).?; try testing.expectEqualStrings("Alice", r1.get("name").?); try testing.expectEqualStrings("30", r1.get("age").?); const r2 = (try it.next()).?; try testing.expectEqualStrings("Bob", r2.get("name").?); } test "example: Table (full parse, random access by position)" { var reader = Io.Reader.fixed("a,b\n1,2\n3,4\n"); var t = try parseTable(&reader, testing.allocator); defer t.deinit(); try testing.expectEqual(@as(usize, 3), t.rows.len); try testing.expectEqualStrings("3", t.rows[2][0]); } test "example: HeaderTable (full parse, random access by header)" { var reader = Io.Reader.fixed("name,score\nAlice,95\nBob,72\n"); var t = try parseHeaderTable(&reader, testing.allocator); defer t.deinit(); try testing.expectEqualStrings("95", t.get(0, "score").?); try testing.expectEqualStrings("Bob", t.get(1, "name").?); }