parseCSV 0.4.3 beta

- Issue #4. Added an option for setting sorting
  type behavior when sorting data.
  Simply set $csv->sort_type to "regular", "numeric",
  or "string".

- Issue #6. Raw loaded file data is now cleared from
  file_data property when it has been successfully
  parsed to keep parseCSV's memory footprint to a
  minimum. Specifically handy when using mulitple
  instances of parseCSV to process large files.

git-svn-id: http://parsecsv-for-php.googlecode.com/svn/trunk@41 339761fc-0c37-0410-822d-8b8cac1f6a97

ChangeLog.txt

@@ -1,3 +1,83 @@
+parseCSV 0.4.3 beta
+-----------------------------------
+Date: 1-July-2008
+
+- Issue #4. Added an option for setting sorting
+  type behavior when sorting data.
+  Simply set $csv->sort_type to "regular", "numeric",
+  or "string".
+
+- Issue #6. Raw loaded file data is now cleared from
+  file_data property when it has been successfully
+  parsed to keep parseCSV's memory footprint to a
+  minimum. Specifically handy when using mulitple
+  instances of parseCSV to process large files.
+
+-----------------------------------
+
+
+parseCSV 0.4.2 beta
+-----------------------------------
+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
+  technically just useless. Instead, the second
+  parameter (filename) doubles as its replacement.
+  Simply put, if filename is not set or null, the
+  output() method will not output a downloadable
+  file. Please update your existing code
+  when using 0.4.2 and later :)
+
+- Small fix to the headers sent by the output()
+  method.
+
+- Added a download example using the output()
+  method to the examples folder.
+
+-----------------------------------
+
+
+parseCSV 0.4.1 beta
+-----------------------------------
+Date: 29-May-2008
+
+- Fixed a small bug in how the output() method
+  handles input data.
+
+-----------------------------------
+
+
+parseCSV 0.4 beta
+-----------------------------------
+Date: 11-Apr-2008
+
+- Error reporting for files/data which is corrupt
+  or has formatting errors like using double
+  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.
+
+I'm calling this a beta release due to the heavy
+modifications to the core parsing logic required
+for error reporting to work. I have tested the
+new code quite extensively, I'm fairly confident
+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
+types of errors, as it's only picking two types
+or syntax errors right now. However, it seems
+these two are the most common errors that you
+would be likely to come across.
+
+-----------------------------------
+
+
 parseCSV 0.3.2
 -----------------------------------
 Date: 1-Apr-2008

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.
+
+?>

parsecsv.lib.php

@@ -4,7 +4,7 @@ class parseCSV {
 	
 /*
 
-	Class: parseCSV v0.3.2
+	Class: parseCSV v0.4.3 beta
 	http://code.google.com/p/parsecsv-for-php/
 	
 	
@@ -94,6 +94,12 @@ class parseCSV {
 	var $sort_by = null;
 	var $sort_reverse = false;
 	
+	# sort behavior passed to ksort/krsort functions
+	# regular = SORT_REGULAR
+	# numeric = SORT_NUMERIC
+	# string  = SORT_STRING
+	var $sort_type = null;
+	
 	# delimiter (comma) and enclosure (double quote)
 	var $delimiter = ',';
 	var $enclosure = '"';
@@ -129,6 +135,8 @@ class parseCSV {
 	var $output_delimiter = ',';
 	var $output_filename = 'data.csv';
 	
+	# keep raw file data in memory after successful parsing (useful for debugging)
+	var $keep_file_data = false;
 	
 	/**
 	 * Internal variables
@@ -140,6 +148,19 @@ class parseCSV {
 	# loaded file contents
 	var $file_data;
 	
+	# error while parsing input data
+	#  0 = No errors found. Everything should be fine :)
+	#  1 = Hopefully correctable syntax error was found.
+	#  2 = Enclosure character (double quote by default)
+	#      was found in non-enclosed field. This means
+	#      the file is either corrupt, or does not
+	#      standard CSV formatting. Please validate
+	#      the parsed data yourself.
+	var $error = 0;
+	
+	# detailed error info
+	var $error_info = array();
+	
 	# array of field values in data parsed
 	var $titles = array();
 	
@@ -170,6 +191,7 @@ class parseCSV {
 	 * @return  nothing
 	 */
 	function parse ($input = null, $offset = null, $limit = null, $conditions = null) {
+		if ( $input === null ) $input = $this->file;
 		if ( !empty($input) ) {
 			if ( $offset !== null ) $this->offset = $offset;
 			if ( $limit !== null ) $this->limit = $limit;
@@ -202,20 +224,19 @@ class parseCSV {
 	
 	/**
 	 * Generate CSV based string for output
-	 * @param   output      if true, prints headers and strings to browser
+	 * @param   filename    if specified, headers and data will be output directly to browser as a downloable file
-	 * @param   filename    filename sent to browser in headers if output is true
 	 * @param   data        2D array with data
 	 * @param   fields      field names
 	 * @param   delimiter   delimiter used to separate data
 	 * @return  CSV data using delimiter of choice, or default
 	 */
-	function output ($output = true, $filename = null, $data = array(), $fields = array(), $delimiter = null) {
+	function output ($filename = null, $data = array(), $fields = array(), $delimiter = null) {
 		if ( empty($filename) ) $filename = $this->output_filename;
 		if ( $delimiter === null ) $delimiter = $this->output_delimiter;
 		$data = $this->unparse($data, $fields, null, null, $delimiter);
-		if ( $output ) {
+		if ( $filename !== null ) {
 			header('Content-type: application/csv');
-			header('Content-Disposition: inline; filename="'.$filename.'"');
+			header('Content-Disposition: attachment; filename="'.$filename.'"');
 			echo $data;
 		}
 		return $data;
@@ -272,12 +293,12 @@ class parseCSV {
 			$pch = ( isset($data{$i-1}) ) ? $data{$i-1} : false ;
 			
 			// open and closing quotes
-			if ( $ch == $enclosure && (!$enclosed || $nch != $enclosure) ) {
+			if ( $ch == $enclosure ) {
-				$enclosed = ( $enclosed ) ? false : true ;
+				if ( !$enclosed || $nch != $enclosure ) {
-			
+					$enclosed = ( $enclosed ) ? false : true ;
-			// inline quotes	
+				} elseif ( $enclosed ) {
-			} elseif ( $ch == $enclosure && $enclosed ) {
+					$i++;
-				$i++;
+				}
 				
 			// end of row
 			} elseif ( ($ch == "\n" && $pch != "\r" || $ch == "\r") && !$enclosed ) {
@@ -311,13 +332,12 @@ class parseCSV {
 		
 		// capture most probable delimiter
 		ksort($filtered);
-		$delimiter = reset($filtered);
+		$this->delimiter = reset($filtered);
-		$this->delimiter = $delimiter;
 		
 		// parse data
 		if ( $parse ) $this->data = $this->parse_string();
 		
-		return $delimiter;
+		return $this->delimiter;
 		
 	}
 	
@@ -349,6 +369,8 @@ class parseCSV {
 			} else return false;
 		}
 		
+		$white_spaces = str_replace($this->delimiter, '', " \t\x0B\0");
+		
 		$rows = array();
 		$row = array();
 		$row_count = 0;
@@ -365,22 +387,66 @@ class parseCSV {
 			$nch = ( isset($data{$i+1}) ) ? $data{$i+1} : false ;
 			$pch = ( isset($data{$i-1}) ) ? $data{$i-1} : false ;
 			
-			// open and closing quotes
+			// open/close quotes, and inline quotes
-			if ( $ch == $this->enclosure && (!$enclosed || $nch != $this->enclosure) ) {
+			if ( $ch == $this->enclosure ) {
-				$enclosed = ( $enclosed ) ? false : true ;
+				if ( !$enclosed ) {
-				if ( $enclosed ) $was_enclosed = true;
+					if ( ltrim($current, $white_spaces) == '' ) {
-			
+						$enclosed = true;
-			// inline quotes	
+						$was_enclosed = true;
-			} elseif ( $ch == $this->enclosure && $enclosed ) {
+					} else {
-				$current .= $ch;
+						$this->error = 2;
-				$i++;
+						$error_row = count($rows) + 1;
+						$error_col = $col + 1;
+						if ( !isset($this->error_info[$error_row.'-'.$error_col]) ) {
+							$this->error_info[$error_row.'-'.$error_col] = array(
+								'type' => 2,
+								'info' => 'Syntax error found on row '.$error_row.'. Non-enclosed fields can not contain double-quotes.',
+								'row' => $error_row,
+								'field' => $error_col,
+								'field_name' => (!empty($head[$col])) ? $head[$col] : null,
+							);
+						}
+						$current .= $ch;
+					}
+				} elseif ($nch == $this->enclosure) {
+					$current .= $ch;
+					$i++;
+				} elseif ( $nch != $this->delimiter && $nch != "\r" && $nch != "\n" ) {
+					for ( $x=($i+1); isset($data{$x}) && ltrim($data{$x}, $white_spaces) == ''; $x++ ) {}
+					if ( $data{$x} == $this->delimiter ) {
+						$enclosed = false;
+						$i = $x;
+					} else {
+						if ( $this->error < 1 ) {
+							$this->error = 1;
+						}
+						$error_row = count($rows) + 1;
+						$error_col = $col + 1;
+						if ( !isset($this->error_info[$error_row.'-'.$error_col]) ) {
+							$this->error_info[$error_row.'-'.$error_col] = array(
+								'type' => 1,
+								'info' =>
+									'Syntax error found on row '.(count($rows) + 1).'. '.
+									'A single double-quote was found within an enclosed string. '.
+									'Enclosed double-quotes must be escaped with a second double-quote.',
+								'row' => count($rows) + 1,
+								'field' => $col + 1,
+								'field_name' => (!empty($head[$col])) ? $head[$col] : null,
+							);
+						}
+						$current .= $ch;
+						$enclosed = false;
+					}
+				} else {
+					$enclosed = false;
+				}
 				
 			// end of field/row
-			} elseif ( ($ch == $this->delimiter || ($ch == "\n" && $pch != "\r") || $ch == "\r") && !$enclosed ) {
+			} elseif ( ($ch == $this->delimiter || $ch == "\n" || $ch == "\r") && !$enclosed ) {
-				if ( !$was_enclosed ) $current = trim($current);
 				$key = ( !empty($head[$col]) ) ? $head[$col] : $col ;
-				$row[$key] = $current;
+				$row[$key] = ( $was_enclosed ) ? $current : trim($current) ;
 				$current = '';
+				$was_enclosed = false;
 				$col++;
 				
 				// end of row
@@ -405,6 +471,7 @@ class parseCSV {
 					if ( $this->sort_by === null && $this->limit !== null && count($rows) == $this->limit ) {
 						$i = $strlen;
 					}
+					if ( $ch == "\r" && $nch == "\n" ) $i++;
 				}
 				
 			// append character to current field
@@ -414,11 +481,20 @@ class parseCSV {
 		}
 		$this->titles = $head;
 		if ( !empty($this->sort_by) ) {
-			( $this->sort_reverse ) ? krsort($rows) : ksort($rows) ;
+			$sort_type = SORT_REGULAR;
+			if ( $this->sort_type == 'numeric' ) {
+				$sort_type = SORT_NUMERIC;
+			} elseif ( $this->sort_type == 'string' ) {
+				$sort_type = SORT_STRING;
+			}
+			( $this->sort_reverse ) ? krsort($rows, $sort_type) : ksort($rows, $sort_type) ;
 			if ( $this->offset !== null || $this->limit !== null ) {
 				$rows = array_slice($rows, ($this->offset === null ? 0 : $this->offset) , $this->limit, true);
 			}
 		}
+		if ( !$this->keep_file_data ) {
+			$this->file_data = null;
+		}
 		return $rows;
 	}
 	
@@ -441,7 +517,7 @@ class parseCSV {
 		$entry = array();
 		
 		// create heading
-		if ( $this->heading && !$append ) {
+		if ( $this->heading && !$append && !empty($fields) ) {
 			foreach( $fields as $key => $value ) {
 				$entry[] = $this->_enclose_value($value);
 			}