From 4f4cc2e7256afee87889ba395785ff8218f260d6 Mon Sep 17 00:00:00 2001
From: Marc Ermshaus <marc@ermshaus.org>
Date: Wed, 7 Sep 2016 16:40:43 +0200
Subject: [PATCH] Add CsvReader::fetch. Add CsvReader docs to readme.

---
 README.md                                     | 55 +++++++++++++++++++
 src/CsvReader.php                             | 17 ++++++
 .../Kaloa/Tests/Filesystem/CsvReaderTest.php  | 19 +++++++
 3 files changed, 91 insertions(+)

diff --git a/README.md b/README.md
index ad31ae2..1446498 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,61 @@ The following PHP versions are supported:
 - HHVM
 
 
+## Documentation
+
+### Usage
+
+#### CsvReader
+
+~~~ php
+use Kaloa\Filesystem\CsvReader;
+
+// General usage. Read all CSV rows from a stream into a numeric array.
+
+$stream = fopen(__DIR__ . '/file.csv');
+$csvReader = new CsvReader($stream);
+$data = $csvReader->fetchAll();
+fclose($stream);
+
+// Read all CSV rows from a stream into an associative array.
+// The first row from the input will be used as keys.
+
+$data = $csvReader->fetchAllAssoc();
+
+// If the file doesn't contain a row with keys, keys can be provided
+// manually.
+
+$data = $csvReader->fetchAllAssoc(array('id', 'title', 'date_added'));
+
+// There's also a streaming mode available.
+
+while ($row = $csvReader->fetch()) {
+    // ...
+}
+
+// Streaming works with associative arrays, too.
+
+while ($row = $csvReader->fetchAssoc()) {
+    // ...
+}
+
+// Respectively:
+
+while ($row = $csvReader->fetchAssoc(array('id', 'title', 'date_added'))) {
+    // ...
+}
+
+// The reader automatically converts all input data to UTF-8. Differing input
+// encodings may be defined in the constructor.
+
+$csvReader = new CsvReader($iso88591stream, 'ISO-8859-1');
+
+// The same goes for non-standard delimiter, enclosure and escape characters.
+
+$csvReader = new CsvReader($stream, 'UTF-8', ':', '|', '%');
+~~~
+
+
 ## Testing
 
 (Tools are not included in this package.)
diff --git a/src/CsvReader.php b/src/CsvReader.php
index 4673748..795fef3 100644
--- a/src/CsvReader.php
+++ b/src/CsvReader.php
@@ -121,6 +121,23 @@ public function fetchAllAssoc(array $keys = array())
         return $data;
     }
 
+    /**
+     * @return array|bool
+     */
+    public function fetch()
+    {
+        $row = $this->getNextRow();
+
+        if (false === $row) {
+            // EOF
+            return false;
+        }
+
+        $row = $this->negotiateEncoding($row);
+
+        return $row;
+    }
+
     /**
      * @param array $keys
      * @return array|bool
diff --git a/tests/Kaloa/Tests/Filesystem/CsvReaderTest.php b/tests/Kaloa/Tests/Filesystem/CsvReaderTest.php
index c6a87cf..8edef62 100644
--- a/tests/Kaloa/Tests/Filesystem/CsvReaderTest.php
+++ b/tests/Kaloa/Tests/Filesystem/CsvReaderTest.php
@@ -113,6 +113,25 @@ public function testCanReadInStreamingMode()
         $expected[] = array('Col a' => 'value 2a', 'Col b' => 'value 2b');
 
         $this->assertSame($expected, $data);
+
+        // Test non-associative fetch method
+
+        $stream = fopen(__DIR__ . '/csv-files/custom-delimiters.csv', 'rb');
+        $reader = new CsvReader($stream, 'UTF-8', ':', '|');
+        $data = array();
+
+        while ($row = $reader->fetch()) {
+            $data[] = $row;
+        }
+
+        fclose($stream);
+
+        $expected = array();
+        $expected[] = array('Col a', 'Col b');
+        $expected[] = array('value 1a', 'value 1b');
+        $expected[] = array('value 2a', 'value 2b');
+
+        $this->assertSame($expected, $data);
     }
 
     /**