Add CsvReader::fetch. Add CsvReader docs to readme.

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.)

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

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);
     }
 
     /**