From 4371f82c4428a7e9f96876d5aeb742278d86e00f Mon Sep 17 00:00:00 2001
From: beho <sperka@gmail.com>
Date: Fri, 15 Jan 2021 12:10:23 +0100
Subject: [PATCH] Basic README.md

---
 README.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5c99e06..6587fa5 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,55 @@
 # zig-csv
 
-[Zig](https://github.com/ziglang/zig) CSV parser library.
+Low-level CSV parser library for [Zig language](https://github.com/ziglang/zig). Each non-empty line in input is parsed as one or more tokens of type `field`, followed by `row_end`.
+
+## Features
+
+- Reads UTF-8 files.
+- Provides iterator interface to stream of tokens. 
+- Handles quoted fields in which column/row separator can be used. Quote itself can be used in field by doubling it (e.g. `"This is quote: ""."`)
+- Configurable column separator(default `,`), row separator (`\n`) and quote (`"`). 
+    - **Currently only single byte characters.**
+- Parser does not allocate – caller provides a buffer that parser operates in. **Buffer must be longer than a longest field in input.**
+
+## Example
+
+Following code reads CSV tokens from a file while very naively printing them as table to standard output. 
+
+```zig
+const std = @import("std");
+const csv = @import("csv");
+
+pub fn main() anyerror!void {
+    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena.deinit();
+
+    const allocator = &arena.allocator;
+    var buffer = try allocator.alloc(u8, 4096);
+
+    const args = try std.process.argsAlloc(allocator);
+    defer std.process.argsFree(allocator, args);
+
+    if (args.len != 2) {
+        std.log.warn("Single arg is expected", .{});
+        std.process.exit(1);
+    }
+
+    const file = try std.fs.cwd().openFile(args[1], .{});
+    defer file.close();
+
+    const csv_tokenizer = &try csv.CsvTokenizer(std.fs.File.Reader).init(file.reader(), buffer, .{});
+    const stdout = std.io.getStdOut().writer();
+
+    while (try csv_tokenizer.next()) |token| {
+        switch (token) {
+            .field => |val| {
+                try stdout.writeAll(val);
+                try stdout.writeAll("\t");
+            },
+            .row_end => {
+                try stdout.writeAll("\n");
+            },
+        }
+    }
+}
+```
-- 
knotmirror 0.0.1