Merge pull request #18 from parsecsv/williamknauss-new-issue-14

williamknauss new issue 14

.gitignore

@@ -0,0 +1,2 @@
+vendor/
+composer.lock

ChangeLog.txt

@@ -1,91 +1,246 @@
-parseCSV 0.2.0 beta
+parseCSV 0.4.3 beta
------------------------------------
+-----------------------------------
-Date: 2-Jan-2007
+Date: 1-July-2008
-
+
-- Added auto() function to automatically detect
+- Issue #4. Added an option for setting sorting
-  delimiter character.
+  type behavior when sorting data.
-  Useful for user upload incase delimiter is
+  Simply set $csv->sort_type to "regular", "numeric",
-  comma (,), tab, or semi-colon (;). Some
+  or "string".
-  versions of MS Excel for Windows use
+
-  semi-colons instead of commas when saving to
+- Issue #6. Raw loaded file data is now cleared from
-  CSV files.
+  file_data property when it has been successfully
-  It uses a process of elimination to eliminate
+  parsed to keep parseCSV's memory footprint to a
-  characters that can not be the delimiter,
+  minimum. Specifically handy when using mulitple
-  so it should work on all CSV-structured files
+  instances of parseCSV to process large files.
-  almost no matter what the delimiter is.
+
-
+-----------------------------------
-- Generally updated some of the core workings
+
-  to increase performance, and offer better 
+
-  support for large (1MB and up) files.
+parseCSV 0.4.2 beta
-
+-----------------------------------
-- Added code examples to header comment.
+Date: 31-May-2008
-
+
------------------------------------
+- IMPORTANT! If you're using the output(),
-
+  method please note that the first parameter
-
+  has been completely removed as it was
-parseCSV 0.1.6 beta
+  technically just useless. Instead, the second
------------------------------------
+  parameter (filename) doubles as its replacement.
-Date: 22-Dec-2006
+  Simply put, if filename is not set or null, the
-
+  output() method will not output a downloadable
-- Updated output() function.
+  file. Please update your existing code
-
+  when using 0.4.2 and later :)
------------------------------------
+
-
+- Small fix to the headers sent by the output()
-
+  method.
-parseCSV 0.1.5 beta
+
------------------------------------
+- Added a download example using the output()
-Date: 22-Dec-2006
+  method to the examples folder.
-
+
-- Added output() function for easy output to
+-----------------------------------
-  browser, for downloading features for example.
+
-
+
------------------------------------
+parseCSV 0.4.1 beta
-
+-----------------------------------
-
+Date: 29-May-2008
-parseCSV 0.1.4 beta
+
------------------------------------
+- Fixed a small bug in how the output() method
-Date: 17-Dec-2006
+  handles input data.
-
+
-- Minor changes and fixes
+-----------------------------------
-
+
------------------------------------
+
-
+parseCSV 0.4 beta
-
+-----------------------------------
-parseCSV 0.1.3 beta
+Date: 11-Apr-2008
------------------------------------
+
-Date: 17-Dec-2006
+- Error reporting for files/data which is corrupt
-
+  or has formatting errors like using double
-- Added GPL v2.0 license.
+  quotes in a field without enclosing quotes. Or
-
+  not escaping double quotes with a second one.
------------------------------------
+
-
+- parse() method does not require input anymore
-
+  if the "$object->file" property has been set.
-parseCSV 0.1.2 beta
+
------------------------------------
+I'm calling this a beta release due to the heavy
-Date: 17-Dec-2006
+modifications to the core parsing logic required
-
+for error reporting to work. I have tested the
-- Added encoding() function for easier character
+new code quite extensively, I'm fairly confident
-  encoding configuration.
+that it still parses exactly as it always has.
-
+
------------------------------------
+The second reason I'm calling it a beta release
-
+is cause I'm sure the error reporting code will
-
+need more refinements and tweaks to detect more
-parseCSV 0.1.1 beta
+types of errors, as it's only picking two types
------------------------------------
+or syntax errors right now. However, it seems
-Date: 24-Nov-2006
+these two are the most common errors that you
-
+would be likely to come across.
-- Added support for a PHP die command on first
+
-  line of csv files if they have a .php extension
+-----------------------------------
-  to protect secure data from being displayed
+
-  directly to the browser.
+
-
+parseCSV 0.3.2
------------------------------------
+-----------------------------------
-
+Date: 1-Apr-2008
-
+
-parseCSV 0.1 beta
+This is primarily a bug-fix release for a critical
------------------------------------
+bug which was brought to my attention.
-Date: 23-Nov-2006
+
-
+- Fixed a critical bug in conditions parsing which
-- Initial release
+  would generate corrupt matching patterns causing
-
+  the condition(s) to not work at all in some
------------------------------------
+  situations.
+
+- Fixed a small code error which would cause PHP to
+  generate a invalid offset notice when zero length
+  values were fed into the unparse() method to
+  generate CSV data from an array.
+
+Notice: If you have been using the "parsecsv-stable"
+branch as an external in any of your projects,
+please use the "stable/parsecsv" branch from this
+point on as I will eventually remove the former due
+to it's stupid naming.
+
+-----------------------------------
+
+
+parseCSV 0.3.1
+-----------------------------------
+Date: 1-Sep-2007
+
+- Small change to default output settings to
+  conform with RFC 4180 (http://rfc.net/rfc4180.html).
+  Only the LF (line feed) character was used
+  by default to separate rows, rather than
+  CRLF (carriage return & line feed).
+
+-----------------------------------
+
+
+parseCSV 0.3.0
+-----------------------------------
+Date: 9-Aug-2007
+
+- Changed to the MIT license.
+
+- Added offset and limit options.
+
+- Added SQL-like conditions for quickly
+  filtering out entries. Documentation on the
+  condition syntax is forthcoming.
+
+- Small parsing modification to comply
+  with some recent changes to the specifications
+  outlined on Wikipedia's Comma-separated values
+  article.
+
+- Minor changes and optimizations, and a few
+  spelling corrections. Oops :)
+
+- Included more complex code examples in the
+  parseCSV download.
+
+-----------------------------------
+
+
+parseCSV 0.2.1
+-----------------------------------
+Date: 8-Aug-2007
+
+- Fixed stupid code which caused auto function
+  to not work in some situations.
+
+-----------------------------------
+
+
+parseCSV 0.2.0 beta
+-----------------------------------
+Date: 2-Jan-2007
+
+- Added auto() function to automatically detect
+  delimiter character.
+  Useful for user upload incase delimiter is
+  comma (,), tab, or semi-colon (;). Some
+  versions of MS Excel for Windows use
+  semi-colons instead of commas when saving to
+  CSV files.
+  It uses a process of elimination to eliminate
+  characters that can not be the delimiter,
+  so it should work on all CSV-structured files
+  almost no matter what the delimiter is.
+
+- Generally updated some of the core workings
+  to increase performance, and offer better 
+  support for large (1MB and up) files.
+
+- Added code examples to header comment.
+
+-----------------------------------
+
+
+parseCSV 0.1.6 beta
+-----------------------------------
+Date: 22-Dec-2006
+
+- Updated output() function.
+
+-----------------------------------
+
+
+parseCSV 0.1.5 beta
+-----------------------------------
+Date: 22-Dec-2006
+
+- Added output() function for easy output to
+  browser, for downloading features for example.
+
+-----------------------------------
+
+
+parseCSV 0.1.4 beta
+-----------------------------------
+Date: 17-Dec-2006
+
+- Minor changes and fixes
+
+-----------------------------------
+
+
+parseCSV 0.1.3 beta
+-----------------------------------
+Date: 17-Dec-2006
+
+- Added GPL v2.0 license.
+
+-----------------------------------
+
+
+parseCSV 0.1.2 beta
+-----------------------------------
+Date: 17-Dec-2006
+
+- Added encoding() function for easier character
+  encoding configuration.
+
+-----------------------------------
+
+
+parseCSV 0.1.1 beta
+-----------------------------------
+Date: 24-Nov-2006
+
+- Added support for a PHP die command on first
+  line of csv files if they have a .php extension
+  to protect secure data from being displayed
+  directly to the browser.
+
+-----------------------------------
+
+
+parseCSV 0.1 beta
+-----------------------------------
+Date: 23-Nov-2006
+
+- Initial release
+
+-----------------------------------

License.txt

@@ -0,0 +1,21 @@
+(The MIT license)
+
+Copyright (c) 2014 Jim Myhrberg.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,129 @@
+# parseCSV
+
+Note: parseCSV is now being revised to PHP 5 standards. If you have an issue or a feature request we encourage you to open an issue.
+
+parseCSV is an easy to use PHP class that reads and writes CSV data properly. It
+fully conforms to the specifications outlined on the on the
+[Wikipedia article][CSV]. It has many advanced features which help make your
+life easier when dealing with CSV data.
+
+This library was originaly created in early 2007 by [jimeh](https://github.com/jimeh) due to the lack of built-in
+and third-party support for handling CSV data in PHP.
+
+[csv]: http://en.wikipedia.org/wiki/Comma-separated_values
+
+
+## Features
+
+* parseCSV is the only complete and fully featured CSV solution for PHP (as
+  far as I know).
+* Supports enclosed values, enclosed commas, double quotes and new lines.
+* Automatic delimiter character detection.
+* Sort data by specific fields/columns.
+* Easy data manipulation.
+* Basic SQL-like _conditions_, _offset_ and _limit_ options for filtering
+  data.
+* Error detection for incorrectly formatted input. It attempts to be
+  intelligent, but can not be trusted 100% due to the structure of CSV, and
+  how different programs like Excel for example outputs CSV data.
+* Support for character encoding conversion using PHP's _iconv_ function
+  (requires PHP 5).
+* Supports both PHP 4 & 5.
+
+
+## Example Usage
+
+**General**
+
+```php
+$csv = new parseCSV('data.csv');
+print_r($csv->data);
+```
+
+**Tab delimited, and encoding conversion**
+
+```php
+$csv = new parseCSV();
+$csv->encoding('UTF-16', 'UTF-8');
+$csv->delimiter = "\t";
+$csv->parse('data.tsv');
+print_r($csv->data);
+```
+
+**Auto-detect delimiter character**
+
+```php
+$csv = new parseCSV();
+$csv->auto('data.csv');
+print_r($csv->data);
+```
+
+**Modify data in a CSV file**
+
+```php
+$csv = new parseCSV();
+$csv->sort_by = 'id';
+$csv->parse('data.csv');
+# "4" is the value of the "id" column of the CSV row
+$csv->data[4] = array('firstname' => 'John', 'lastname' => 'Doe', 'email' => 'john@doe.com');
+$csv->save();
+```
+
+**Add row/entry to end of CSV file**
+
+_Only recommended when you know the extact sctructure of the file._
+
+```php
+$csv = new parseCSV();
+$csv->save('data.csv', array('1986', 'Home', 'Nowhere', ''), true);
+```
+
+**Convert 2D array to csv data and send headers to browser to treat output as
+a file and download it**
+
+```php
+$csv = new parseCSV();
+$csv->output('movies.csv', $array, array('field 1', 'field 2'), ',');
+```
+
+
+## Credits
+
+* parseCSV is based on the concept of [Ming Hong Ng][ming]'s [CsvFileParser][]
+  class.
+
+[ming]: http://minghong.blogspot.com/
+[CsvFileParser]: http://minghong.blogspot.com/2006/07/csv-parser-for-php.html
+
+
+## Contributors
+
+Please find a complete list on the project's [contributors][] page.
+
+[contributors]: https://github.com/parsecsv/parsecsv-for-php/graphs/contributors
+
+
+
+## License
+
+(The MIT license)
+
+Copyright (c) 2014 Jim Myhrberg.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

composer.json

@@ -0,0 +1,17 @@
+{
+    "name": "parsecsv/php-parsecsv",
+    "description": "CSV data parser for PHP",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Jim Myhrberg",
+            "email": "contact@jimeh.me"
+        }
+    ],
+    "autoload": {
+        "classmap": ["."]
+    },
+    "require-dev": {
+        "phpunit/phpunit": "4.1.*"
+    }
+}

examples/_books.csv

@@ -0,0 +1,15 @@
+rating,title,author,type,asin,tags,review
+0,The Killing Kind,John Connolly,Book,0340771224,,i still haven't had time to read this one...
+0,The Third Secret,Steve Berry,Book,0340899263,,need to find time to read this book
+3,The Last Templar,Raymond Khoury,Book,0752880705,,
+5,The Traveller,John Twelve Hawks,Book,059305430X,,
+4,Crisis Four,Andy Mcnab,Book,0345428080,,
+5,Prey,Michael Crichton,Book,0007154534,,
+3,The Broker (Paperback),John Grisham,Book,0440241588,book johngrisham,"good book, but is slow in the middle"
+3,Without Blood (Paperback),Alessandro Baricco,Book,1841955744,,
+5,State of Fear (Paperback),Michael Crichton,Book,0061015733,,
+4,The Rule of Four (Paperback),Ian Caldwell,Book,0099451956,book bestseller,
+4,Deception Point (Paperback),Dan Brown,Book,0671027387,book danbrown bestseller,
+5,Digital Fortress : A Thriller (Mass Market Paperback),Dan Brown,Book,0312995423,book danbrown bestseller,
+5,Angels & Demons (Mass Market Paperback),Dan Brown,Book,0671027360,book danbrown bestseller,
+4,The Da Vinci Code (Hardcover),Dan Brown,"   Book   ",0385504209,book movie danbrown bestseller davinci,

examples/basic.php

@@ -0,0 +1,48 @@
+<pre>
+<?php
+
+
+# include parseCSV class.
+require_once('../parsecsv.lib.php');
+
+
+# create new parseCSV object.
+$csv = new parseCSV();
+
+
+# Parse '_books.csv' using automatic delimiter detection...
+$csv->auto('_books.csv');
+
+# ...or if you know the delimiter, set the delimiter character
+# if its not the default comma...
+// $csv->delimiter = "\t";   # tab delimited
+
+# ...and then use the parse() function.
+// $csv->parse('_books.csv');
+
+
+# Output result.
+// print_r($csv->data);
+
+
+?>
+</pre>
+<style type="text/css" media="screen">
+	table { background-color: #BBB; }
+	th { background-color: #EEE; }
+	td { background-color: #FFF; }
+</style>
+<table border="0" cellspacing="1" cellpadding="3">
+	<tr>
+		<?php foreach ($csv->titles as $value): ?>
+		<th><?php echo $value; ?></th>
+		<?php endforeach; ?>
+	</tr>
+	<?php foreach ($csv->data as $key => $row): ?>
+	<tr>
+		<?php foreach ($row as $value): ?>
+		<td><?php echo $value; ?></td>
+		<?php endforeach; ?>
+	</tr>
+	<?php endforeach; ?>
+</table>

examples/conditions.php

@@ -0,0 +1,48 @@
+<pre>
+<?php
+
+
+# include parseCSV class.
+require_once('../parsecsv.lib.php');
+
+
+# create new parseCSV object.
+$csv = new parseCSV();
+
+
+# Example conditions:
+// $csv->conditions = 'title contains paperback OR title contains hardcover';
+$csv->conditions = 'author does not contain dan brown';
+// $csv->conditions = 'rating < 4 OR author is John Twelve Hawks';
+// $csv->conditions = 'rating > 4 AND author is Dan Brown';
+
+
+# Parse '_books.csv' using automatic delimiter detection.
+$csv->auto('_books.csv');
+
+
+# Output result.
+// print_r($csv->data);
+
+
+?>
+</pre>
+<style type="text/css" media="screen">
+	table { background-color: #BBB; }
+	th { background-color: #EEE; }
+	td { background-color: #FFF; }
+</style>
+<table border="0" cellspacing="1" cellpadding="3">
+	<tr>
+		<?php foreach ($csv->titles as $value): ?>
+		<th><?php echo $value; ?></th>
+		<?php endforeach; ?>
+	</tr>
+	<?php foreach ($csv->data as $key => $row): ?>
+	<tr>
+		<?php foreach ($row as $value): ?>
+		<td><?php echo $value; ?></td>
+		<?php endforeach; ?>
+	</tr>
+	<?php endforeach; ?>
+</table>

examples/download.php

@@ -0,0 +1,34 @@
+<?php
+
+
+# include parseCSV class.
+require_once('../parsecsv.lib.php');
+
+
+# create new parseCSV object.
+$csv = new parseCSV();
+
+
+# Parse '_books.csv' using automatic delimiter detection...
+$csv->auto('_books.csv');
+
+# ...or if you know the delimiter, set the delimiter character
+# if its not the default comma...
+// $csv->delimiter = "\t";   # tab delimited
+
+# ...and then use the parse() function.
+// $csv->parse('_books.csv');
+
+# now we have data in $csv->data, at which point we can modify
+# it to our hearts content, like removing the last item...
+array_pop($csv->data);
+
+# then we output the file to the browser as a downloadable file...
+$csv->output('books.csv');
+# ...when the first parameter is given and is not null, the
+# output method will itself send the correct headers and the
+# data to download the output as a CSV file. if it's not set
+# or is set to null, output will only return the generated CSV
+# output data, and will not output to the browser itself.
+
+?>

examples/limit.php

@@ -0,0 +1,61 @@
+<pre>
+<?php
+
+
+# include parseCSV class.
+require_once('../parsecsv.lib.php');
+
+
+# create new parseCSV object.
+$csv = new parseCSV();
+
+
+# if sorting is enabled, the whole CSV file
+# will be processed and sorted and then rows
+# are extracted based on offset and limit.
+#
+# if sorting is not enabled, then the least
+# amount of rows to satisfy offset and limit
+# settings will be processed. this is useful
+# with large files when you only need the
+# first 20 rows for example.
+$csv->sort_by = 'title';
+
+
+# offset from the beginning of the file,
+# ignoring the first X number of rows.
+$csv->offset = 2;
+
+# limit the number of returned rows.
+$csv->limit = 3;
+
+
+# Parse '_books.csv' using automatic delimiter detection.
+$csv->auto('_books.csv');
+
+
+# Output result.
+// print_r($csv->data);
+
+
+?>
+</pre>
+<style type="text/css" media="screen">
+	table { background-color: #BBB; }
+	th { background-color: #EEE; }
+	td { background-color: #FFF; }
+</style>
+<table border="0" cellspacing="1" cellpadding="3">
+	<tr>
+		<?php foreach ($csv->titles as $value): ?>
+		<th><?php echo $value; ?></th>
+		<?php endforeach; ?>
+	</tr>
+	<?php foreach ($csv->data as $key => $row): ?>
+	<tr>
+		<?php foreach ($row as $value): ?>
+		<td><?php echo $value; ?></td>
+		<?php endforeach; ?>
+	</tr>
+	<?php endforeach; ?>
+</table>