From 03a4328be5b797020f00d6f5dd4f3449d1f6d47e Mon Sep 17 00:00:00 2001
From: shimies <shimies@duck.com>
Date: Tue, 23 Sep 2025 16:59:46 +0900
Subject: [PATCH 1/2] Update README.md

---
 README.md | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 99ddc81..f5d9040 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,35 @@
-## libcsv
-Minimal implimentation of CSV parser and formatter for the following formats
+## libcsv-java
+Minimal implementation of CSV parser and formatter written in java for the following formats
 - [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180)
+
+### Runtime requirements
+- JRE 17+
+
+### Example
+```java
+var parser = CsvParsers.ofStrictRfc4180(true);
+var records =
+        parser.parseString(
+                """
+                circle,"r=5,0"
+                square,"d=2,0"
+                """);
+assertThat(records).containsExactly(List.of("circle", "r=5,0"), List.of("square", "d=2,0"));
+```
+
+```java
+var parser = CsvParsers.ofStrictRfc4180(true);
+var records = new ArrayList<List<String>>();
+try (var anyReader = new StringReader(
+        """
+        a,b
+        c,d
+        """)) {
+  var reader = parser.newRecordReader(anyReader);
+  while (reader.hasMoreRecord()) {
+    records.add(reader.readRecord());
+  }
+} catch (IOException e) { }
+
+assertThat(records).containsExactly(List.of("a", "b"), List.of("c", "d"));
+```
\ No newline at end of file

From 40b068d3950dc71f0c68454092ef5b13b2ca1db4 Mon Sep 17 00:00:00 2001
From: shimies <shimies@duck.com>
Date: Tue, 23 Sep 2025 17:49:28 +0900
Subject: [PATCH 2/2] Revise further

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 63 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f5d9040..a3d678a 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,22 @@
 ## libcsv-java
-Minimal implementation of CSV parser and formatter written in java for the following formats
+Minimal implementation of CSV parsers and formatters written in java for the following formats
 - [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180)
 
+
 ### Runtime requirements
 - JRE 17+
 
+
+### Overview
+The central APIs of parsing and formatting CSVs are `CsvParser` class and `CsvFormatter` class.
+Parsers only unmarshal a CSV record into `List<String>` and formatters only marshal `List<String>` into a CSV record for now.
+See the javadoc for full API documentation.
+
+
 ### Example
+#### Parsing CSV
+You can parse a CSV from a string using `CsvParser#parseString(String)` or a file using `CsvParser#parseString(Path, Charset)`:
+
 ```java
 var parser = CsvParsers.ofStrictRfc4180(true);
 var records =
@@ -14,9 +25,13 @@ var records =
                 circle,"r=5,0"
                 square,"d=2,0"
                 """);
-assertThat(records).containsExactly(List.of("circle", "r=5,0"), List.of("square", "d=2,0"));
+
+// assertThat(records).containsExactly(List.of("circle", "r=5,0"), List.of("square", "d=2,0"));
 ```
 
+For large files or streaming, use `RecordReader` which allows you to write an interator-like way to access a record at a time.
+`RecordReader` can be created by `CsvParser#newRecordReader(Reader)`.
+
 ```java
 var parser = CsvParsers.ofStrictRfc4180(true);
 var records = new ArrayList<List<String>>();
@@ -29,7 +44,50 @@ try (var anyReader = new StringReader(
   while (reader.hasMoreRecord()) {
     records.add(reader.readRecord());
   }
-} catch (IOException e) { }
+}
+
+// assertThat(records).containsExactly(List.of("a", "b"), List.of("c", "d"));
+```
+
+#### Formatting CSV
+You can format records into a CSV from a string using `CsvFormatter#formatToString(List<String>)` or a file using `CsvFormatter#formatToFile(List<String>, Path, Charset)`:
+
+
+```java
+var formatter = CsvFormatters.ofRfc4180();
+var records = List.of(List.of("1", "2"), List.of("Hello", "World"));
+var sink = Files.createTempFile("test", ".csv");
+formatter.formatToFile(records, sink, StandardCharsets.UTF_8);
+
+// assertThat(sink).hasContent("1,2\r\nHello,World\r\n");
+```
+
+For large number of records or streaming, use `RecordWriter` which allows you to write an interator-like way to format a record at a time.
+`RecordWriter` can be created by `CsvFormatter#newRecordWriter(Writer)`.
+
+
+```java
+var formatter = CsvFormatters.ofRfc4180();
+var records = List.of(List.of("1", "2"), List.of("Hello", "World"));
+var sink = Files.createTempFile("test", ".csv");
+try (var bw = Files.newBufferedWriter(sink, StandardCharsets.UTF_8)) {
+  var writer = formatter.newRecordWriter(bw);
+  for (var record : records) {
+    writer.writeRecord(record);
+  }
+}
+
+// assertThat(sink).hasContent("1,2\r\nHello,World\r\n");
+```
+
+
+### References
+For more details and API usage, see the javadoc in the source files and the test cases.
+
+#### Parsers
+- [CsvParsers](https://github.com/shimies/libcsv-java/blob/main/lib/src/main/java/io/github/shimies/csv/CsvParsers.java)
+- [CsvParser](https://github.com/shimies/libcsv-java/blob/main/lib/src/main/java/io/github/shimies/csv/CsvParser.java)
 
-assertThat(records).containsExactly(List.of("a", "b"), List.of("c", "d"));
-```
\ No newline at end of file
+#### Formatters
+- [CsvFormatters](https://github.com/shimies/libcsv-java/blob/main/lib/src/main/java/io/github/shimies/csv/CsvFormatters.java)
+- [CsvFormatter](https://github.com/shimies/libcsv-java/blob/main/lib/src/main/java/io/github/shimies/csv/CsvFormatter.java)