Improve README

htmlburger · Sep 15, 2017 · 2bb6f78 · 2bb6f78
1 parent 9f6e857
commit 2bb6f78
Showing 1 changed file with 82 additions and 61 deletions.
diff --git a/README.md b/README.md
@@ -1,83 +1,108 @@
 Carbon CSV
 ==========
 
-Carbon CSV is a PHP library, that helps you easily parse CSV files.
-Parse any CSV file to an easy to use associative array.
+Carbon CSV is a PHP library aimed at simplifying CSV parsing.
 
-## Features
-
-There are a number of helpful features that include:
-
-* reduced memory usage and size, thanks to the [`SplFileObject`](http://php.net/manual/en/class.splfileobject.php) PHP class;
-* skip row until (by index);
-* skip specific columns (by index);
-* column removal from parsed output (by index - single or multiple columns). If you wish to remove columns you don't need to work with;
-* set custom column names, which will help you when using the parsed output.
+It provides simple interface to ease mapping columns via a header row, or custom column names. 
 
 ## Installation
 
-It is recommended to install the library through [Composer](https://getcomposer.org/).
-
 ```bash
 composer require htmlburger/carbon-csv
 ```
 
 ## Usage
 
-To parse a simple CSV file, use the following code:
+Suppose that you have the following CSV:
 
-```php
-use \Carbon_CSV\CsvFile as CsvFile;
-use \Carbon_CSV\Exception;
+| First Name | Last Name | Company Name                    | Address                             |
+|------------|-----------|---------------------------------|-------------------------------------|
+| Homer      | Simpson   | Springfield Nuclear Power Plant |  742 Evergreen Terrace, Springfield |
+| Ned        | Flanders  | The Leftorium                   | 744 Evergreen Terrace, Springfield  |
 
-$csv = new CsvFile('path-to-file/filename.csv');
-foreach ($csv as $row) {
-    /* do something with $row*/
+Here is how you could iterate through the rows:
+
+```php
+use \Carbon_CSV\CsvFile;
+use \Carbon_CSV\Exception as CsvException;
+
+try {
+    $csv = new CsvFile('path-to-file/filename.csv');
+    $csv->use_first_row_as_header();
+
+    foreach ($csv as $row) {
+        print_r($row);
+    }
+} catch (CsvException $e) {
+    exit("Couldn't parse CSV file: " . $e->getMessage()); 
 }
 ```
 
-You can iterate the `$csv` object directly, or get all the rows using the `to_array` method.
+Would produce the following output: 
 
-**Important:** the above approach is preferred, as it's less taxing - memory wise (it only works with one row at a time, and doesn't hold all of them, like `to_array` does).
+```
+Array
+(
+    [First Name] => Homer
+    [Last Name] => Simpson
+    [Company Name] => Springfield Nuclear Power Plant
+    [Address] => 742 Evergreen Terrace, Springfield
+)
+Array
+(
+    [First Name] => Ned
+    [Last Name] => Flanders
+    [Company Name] => The Leftorium
+    [Address] => 744 Evergreen Terrace, Springfield
+)
+```
 
-Here's an example with the `to_array` method.
+Alternatively, you could also provide your own column names:
 
 ```php
-use \Carbon_CSV\CsvFile as CsvFile;
-use \Carbon_CSV\Exception;
-
-$csv = new CsvFile('path-to-file/filename.csv');
-$rows = $csv->to_array();
+use \Carbon_CSV\CsvFile;
+use \Carbon_CSV\Exception as CsvException;
+
+try {
+    $csv = new CsvFile('path-to-file/filename.csv');
+    $csv->use_first_row_as_header();
+    $csv->set_column_names([
+        'First Name'   => 'fname',
+        'Last Name'    => 'lname',
+        'Company Name' => 'company',
+        'Address'      => 'address',
+    ]);
+
+    foreach ($csv as $row) {
+        print_r($row);
+    }
+} catch (CsvException $e) {
+    exit("Couldn't parse CSV file: " . $e->getMessage()); 
+}
 ```
 
-This will parse the file and assign the result to the `$rows` variable.
-
-Output:
+Would produce the following output: 
 
 ```
 Array
 (
-    [0] => Array
-        (
-            [0] => John
-            [1] => Doe
-            [2] => Simple Company Name
-            [3] => Street Name, 1234, City Name, Country Name
-        )
-    [1] => Array
-        (
-            [0] => Jane
-            [1] => Doe
-            [2] => Nice Company Name
-            [3] => Street Name, 5678, City Name, Country Name
-        )
+    [fname] => Homer
+    [lname] => Simpson
+    [company] => Springfield Nuclear Power Plant
+    [address] => 742 Evergreen Terrace, Springfield
+)
+Array
+(
+    [fname] => Ned
+    [lname] => Flanders
+    [company] => The Leftorium
+    [address] => 744 Evergreen Terrace, Springfield
 )
-
 ```
 
 **MacOS encoding**
 
-When working with files created on a Mac device, it's advised to set the `auto_detect_line_endings` PHP variable to `1`.
+When working with files created on a Mac device, you should set the `auto_detect_line_endings` PHP variable to `1`.
 
 ```
 ini_set( 'auto_detect_line_endings', 1 );
@@ -99,11 +124,9 @@ $rows = $csv->to_array();
 
 ### Methods
 
-```
-Please note, that skipping methods work with zero based indexes.
-```
+Methods for skipping rows or columns work with zero based indexes.
 
-#### skip_to_row
+#### `skip_to_row(int $row_index)`
 
 To skip to a specific row, simply pass the index of the row.
 
@@ -156,7 +179,7 @@ Array
 
 ```
 
-#### skip_to_column
+#### `skip_to_column(int $col_index)`
 
 To skip to a specific column, simply pass the index of the column.
 
@@ -210,12 +233,10 @@ Array
 
 ```
 
-#### skip_columns
+#### `skip_columns(array $col_indexes)`
 
 To skip multiple columns, pass the indexes of those columns as an array.
 
-**Important:** when skipping, indexes are reset to start from 0, so you don't need to remember which indexes are available.
-
 ```php
 use \Carbon_CSV\CsvFile as CsvFile;
 use \Carbon_CSV\Exception;
@@ -264,11 +285,11 @@ Array
 
 ```
 
-#### use_first_row_as_header
+#### `use_first_row_as_header()`
 
 To use the first row from the CSV, simply call this method.
 
-**Important:** if the `skip_to_row` is called prior to calling this method, the parser will use the row it's set to skip to, as the header row.
+**Note:** if `skip_to_row` is called prior to calling `use_first_row_as_header`, the parser will use the new first row as a header. 
 
 ```php
 use \Carbon_CSV\CsvFile as CsvFile;
@@ -322,11 +343,11 @@ Array
 
 Since we're telling the parser to use the first row as a header row, it is assigned and skipped.
 
-#### set_column_names
+#### `set_column_names(array $columns_mapping)`
 
 If you wish to use your own indexes for the columns, pass them using an array.
 
-**Important:** you can use this method with `use_first_row_as_header`, so you can set the names of the columns based on the header row.
+**Note:** you can use `set_column_names` in conjunction with `use_first_row_as_header`, so you can set the names of the columns based on the header row.
 
 Example without `use_first_row_as_header` (using a file without a head row):
 
@@ -458,9 +479,9 @@ Array
 )
 ```
 
-#### count
+#### `count()`
 
-Get the total number of rows in the CSV file (please note, that this skips the empty rows);
+Get the total number of rows in the CSV file (this skips the empty rows):
 
 ```php
 use \Carbon_CSV\CsvFile as CsvFile;