Improve examples and documentation for CSV format

Author: clue

README.md

@@ -24,6 +24,7 @@ rows efficiently without having to load the whole file into memory at once.
 
 **Table of contents**
 
+* [CSV format](#csv-format)
 * [Usage](#usage)
   * [Decoder](#decoder)
   * [Encoder](#encoder)
@@ -32,6 +33,77 @@ rows efficiently without having to load the whole file into memory at once.
 * [License](#license)
 * [More](#more)
 
+## CSV format
+
+CSV (Comma-Separated Values or less commonly Character-Separated Values) is a
+very simple text-based format for storing a large number of (uniform) records,
+such as a list of user records or log entries.
+
+```
+Alice,30
+Bob,50
+Carol,40
+Dave,30
+```
+
+While this may look somewhat trivial, this simplicity comes at a price. CSV is
+limited to untyped, two-dimensional data, so there's no standard way of storing
+any nested structures or to differentiate a boolean value from a string or
+integer.
+
+CSV allows for optional field names. Whether field names are used is
+application-dependant, so this library makes no attempt at *guessing* whether
+the first line contains field names or field values. For many common use cases
+it's a good idea to include them like this:
+
+```
+name,age
+Alice,30
+Bob,50
+Carol,40
+Dave,30
+```
+
+CSV allows handling field values that contain spaces or the delimiting comma
+(think of URLs or user-provided descriptions) by enclosing them with quotes like
+this:
+
+```
+name,comment
+Alice,"Yes, I like cheese"
+Bob,"Hello World!"
+```
+
+> Note that these more advanced parsing rules are often handled inconsistently
+  by other applications. Nowadays, these parsing rules are defined as part of
+  [RFC 4180](https://tools.ietf.org/html/rfc4180), however many applications
+  starting using some CSV-variant long before this standard was defined.
+
+Some applications refer to CSV as Character-Separated Values, simply because
+using another delimiter (such as semicolon or tab) is a rather common approach
+to avoid the need to enclose common values in quotes. This is particularly
+common for European systems that use a comma as decimal separator.
+
+```
+name;comment
+Alice;Yes, I like cheese
+Bob;Turn 22,5 degree clockwise
+```
+
+CSV files are often limited to only ASCII characters for best interoperability.
+However, many legacy CSV files often use ISO 8859-1 encoding or some other
+variant. Newer CSV files are usually best saved as UTF-8 and may thus also
+contain special characters from the Unicode range. The text-encoding is usually
+application-dependant, so your best bet would be to convert to (or assume) UTF-8
+consistently.
+
+Despite its shortcomings CSV is widely used and this is unlikely to change any
+time soon. In particular, CSV is a very common export format for a lot of tools
+to interface with spreadsheet processors (such as Exel, Calc etc.). This means
+that CSV is often used for historial reasons and using CSV to store structured
+application data is usually not a good idea nowadays – but exporting to CSV for
+known applications is a very reasonable approach.
+
 ## Usage
 
 ### Decoder

examples/01-count.php

@@ -0,0 +1,40 @@
+<?php
+
+use Clue\React\Csv\Decoder;
+use React\EventLoop\Factory;
+use React\Stream\ReadableResourceStream;
+use React\Stream\WritableResourceStream;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+
+$exit = 0;
+$in = new ReadableResourceStream(STDIN, $loop);
+$info = new WritableResourceStream(STDERR, $loop);
+
+$delimiter = isset($argv[1]) ? $argv[1] : ',';
+
+$decoder = new Decoder($in, $delimiter);
+
+$count = 0;
+$decoder->on('data', function () use (&$count) {
+    ++$count;
+});
+
+$decoder->on('end', function () use (&$count) {
+    echo $count . PHP_EOL;
+});
+
+$decoder->on('error', function (Exception $e) use (&$count, &$exit, $info) {
+    $info->write('ERROR after record ' . $count . ': ' . $e->getMessage() . PHP_EOL);
+    $exit = 1;
+});
+
+$info->write('You can pipe/write a valid CSV stream to STDIN' . PHP_EOL);
+$info->write('The resulting number of records (rows) will be printed to STDOUT' . PHP_EOL);
+$info->write('Invalid CSV will raise an error on STDERR and exit with code 1' . PHP_EOL);
+
+$loop->run();
+
+exit($exit);

examples/validate.php examples/02-validate.phpexamples/validate.php renamed to examples/02-validate.php

@@ -15,8 +15,10 @@
 $out = new WritableResourceStream(STDOUT, $loop);
 $info = new WritableResourceStream(STDERR, $loop);
 
-$decoder = new Decoder($in);
-$encoder = new Encoder($out);
+$delimiter = isset($argv[1]) ? $argv[1] : ',';
+
+$decoder = new Decoder($in, $delimiter);
+$encoder = new Encoder($out, $delimiter);
 $decoder->pipe($encoder);
 
 $decoder->on('error', function (Exception $e) use ($info, &$exit) {