Header support (CSV-65)

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/csv/trunk@1301852 13f79535-47bb-0310-9956-ffa450edef68

Author: ebourg

src/main/java/org/apache/commons/csv/CSVFormat.java

@@ -31,6 +31,7 @@ public class CSVFormat implements Serializable {
 
     /** According to RFC 4180, line breaks are delimited by CRLF */
     private static final String CRLF = "\r\n";
+    
     private final char delimiter;
     private final char encapsulator;
     private final char commentStart;
@@ -39,7 +40,8 @@ public class CSVFormat implements Serializable {
     private final boolean trailingSpacesIgnored;
     private final boolean unicodeEscapesInterpreted;
     private final boolean emptyLinesIgnored;
-    private final String lineSeparator; // for output
+    private final String lineSeparator; // for outputs
+    private final String[] header;
 
 
     /**
@@ -51,7 +53,7 @@ public class CSVFormat implements Serializable {
     static final char DISABLED = '\ufffe';
 
     /** Standard comma separated format as defined by <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>. */
-    public static final CSVFormat DEFAULT = new CSVFormat(',', '"', DISABLED, DISABLED, true, true, false, true, CRLF);
+    public static final CSVFormat DEFAULT = new CSVFormat(',', '"', DISABLED, DISABLED, true, true, false, true, CRLF, null);
 
     /**
      * Excel file format (using a comma as the value delimiter).
@@ -64,10 +66,10 @@ public class CSVFormat implements Serializable {
      * 
      * <pre>CSVFormat fmt = CSVFormat.EXCEL.withDelimiter(';');</pre>
      */
-    public static final CSVFormat EXCEL = new CSVFormat(',', '"', DISABLED, DISABLED, false, false, false, false, CRLF);
+    public static final CSVFormat EXCEL = new CSVFormat(',', '"', DISABLED, DISABLED, false, false, false, false, CRLF, null);
 
     /** Tab-delimited format, with quote; leading and trailing spaces ignored. */
-    public static final CSVFormat TDF = new CSVFormat('\t', '"', DISABLED, DISABLED, true, true, false, true, CRLF);
+    public static final CSVFormat TDF = new CSVFormat('\t', '"', DISABLED, DISABLED, true, true, false, true, CRLF, null);
 
     /**
      * Default MySQL format used by the <tt>SELECT INTO OUTFILE</tt> and
@@ -77,7 +79,7 @@ public class CSVFormat implements Serializable {
      * 
      * @see <a href="http://dev.mysql.com/doc/refman/5.1/en/load-data.html">http://dev.mysql.com/doc/refman/5.1/en/load-data.html</a>
      */
-    public static final CSVFormat MYSQL = new CSVFormat('\t', DISABLED, DISABLED, '\\', false, false, false, false, "\n");
+    public static final CSVFormat MYSQL = new CSVFormat('\t', DISABLED, DISABLED, '\\', false, false, false, false, "\n", null);
 
 
     /**
@@ -92,6 +94,7 @@ public class CSVFormat implements Serializable {
      * @param unicodeEscapesInterpreted <tt>true</tt> when unicode escapes should be interpreted
      * @param emptyLinesIgnored         <tt>true</tt> when the parser should skip emtpy lines
      * @param lineSeparator             the line separator to use for output
+     * @param header                    the header
      */
     CSVFormat(
             char delimiter,
@@ -102,7 +105,8 @@ public class CSVFormat implements Serializable {
             boolean trailingSpacesIgnored,
             boolean unicodeEscapesInterpreted,
             boolean emptyLinesIgnored,
-            String lineSeparator) {
+            String lineSeparator,
+            String[] header) {
         this.delimiter = delimiter;
         this.encapsulator = encapsulator;
         this.commentStart = commentStart;
@@ -112,6 +116,7 @@ public class CSVFormat implements Serializable {
         this.unicodeEscapesInterpreted = unicodeEscapesInterpreted;
         this.emptyLinesIgnored = emptyLinesIgnored;
         this.lineSeparator = lineSeparator;
+        this.header = header;
     }
 
     /**
@@ -171,7 +176,7 @@ public CSVFormat withDelimiter(char delimiter) {
             throw new IllegalArgumentException("The delimiter cannot be a line break");
         }
 
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     /**
@@ -195,7 +200,7 @@ public CSVFormat withEncapsulator(char encapsulator) {
             throw new IllegalArgumentException("The encapsulator cannot be a line break");
         }
 
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     boolean isEncapsulating() {
@@ -223,7 +228,7 @@ public CSVFormat withCommentStart(char commentStart) {
             throw new IllegalArgumentException("The comment start character cannot be a line break");
         }
 
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     /**
@@ -256,7 +261,7 @@ public CSVFormat withEscape(char escape) {
             throw new IllegalArgumentException("The escape character cannot be a line break");
         }
 
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     boolean isEscaping() {
@@ -280,7 +285,7 @@ public boolean isLeadingSpacesIgnored() {
      * @return A copy of this format with the specified left trimming behavior.
      */
     public CSVFormat withLeadingSpacesIgnored(boolean leadingSpacesIgnored) {
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     /**
@@ -300,7 +305,7 @@ public boolean isTrailingSpacesIgnored() {
      * @return A copy of this format with the specified right trimming behavior.
      */
     public CSVFormat withTrailingSpacesIgnored(boolean trailingSpacesIgnored) {
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     /**
@@ -311,7 +316,7 @@ public CSVFormat withTrailingSpacesIgnored(boolean trailingSpacesIgnored) {
      * @return A copy of this format with the specified trimming behavior.
      */
     public CSVFormat withSurroundingSpacesIgnored(boolean surroundingSpacesIgnored) {
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, surroundingSpacesIgnored, surroundingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, surroundingSpacesIgnored, surroundingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     /**
@@ -332,7 +337,7 @@ public boolean isUnicodeEscapesInterpreted() {
      * @return A copy of this format with the specified unicode escaping behavior.
      */
     public CSVFormat withUnicodeEscapesInterpreted(boolean unicodeEscapesInterpreted) {
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     /**
@@ -352,7 +357,7 @@ public boolean isEmptyLinesIgnored() {
      * @return A copy of this format  with the specified empty line skipping behavior.
      */
     public CSVFormat withEmptyLinesIgnored(boolean emptyLinesIgnored) {
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     /**
@@ -372,15 +377,37 @@ public String getLineSeparator() {
      * @return A copy of this format using the specified output line separator
      */
     public CSVFormat withLineSeparator(String lineSeparator) {
-        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator);
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
+    }
+
+    String[] getHeader() {
+        return header;
+    }
+
+    /**
+     * Returns a copy of this format using the specified header. The header can
+     * either be parsed automatically from the input file with:
+     *
+     * <pre>CSVFormat format = CSVFormat.DEFAULT.withHeader();</pre>
+     *
+     * or specified manually with:
+     *
+     * <pre>CSVFormat format = CSVFormat.DEFAULT.withHeader("name", "email", "phone");</pre>
+     *
+     * @param header the header, <tt>null</tt> if disabled, empty if parsed automatically, user specified otherwise.
+     *
+     * @return A copy of this format using the specified header
+     */
+    public CSVFormat withHeader(String... header) {
+        return new CSVFormat(delimiter, encapsulator, commentStart, escape, leadingSpacesIgnored, trailingSpacesIgnored, unicodeEscapesInterpreted, emptyLinesIgnored, lineSeparator, header);
     }
 
     /**
      * Parses the specified content.
      * 
      * @param in the input stream
      */
-    public Iterable<String[]> parse(Reader in) {
+    public Iterable<CSVRecord> parse(Reader in) throws IOException {
         return new CSVParser(in, this);
     }
 

src/main/java/org/apache/commons/csv/CSVParser.java

@@ -21,8 +21,10 @@
 import java.io.Reader;
 import java.io.StringReader;
 import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Map;
 import java.util.NoSuchElementException;
 
 import org.apache.commons.csv.CSVLexer.Token;
@@ -40,14 +42,14 @@
  * <pre>
  * CSVFormat format = new CSVFormat('\t', '"', '#');
  * Reader in = new StringReader("a\tb\nc\td");
- * String[][] records = new CSVParser(in, format).getRecords();
+ * List&lt;CSVRecord> records = new CSVParser(in, format).getRecords();
  * </pre>
  *
  * <p>Parsing of a csv-string in Excel CSV format, using a for-each loop:</p>
  * <pre>
  * Reader in = new StringReader("a;b\nc;d");
  * CSVParser parser = new CSVParser(in, CSVFormat.EXCEL);
- * for (String[] record : parser) {
+ * for (CSVRecord record : parser) {
  *     ...
  * }
  * </pre>
@@ -59,13 +61,11 @@
  * <p>see <a href="package-summary.html">package documentation</a>
  * for more details</p>
  */
-public class CSVParser implements Iterable<String[]> {
-
-    /** Immutable empty String array. */
-    private static final String[] EMPTY_STRING_ARRAY = new String[0];
+public class CSVParser implements Iterable<CSVRecord> {
 
     private final CSVLexer lexer;
-    
+    private Map<String, Integer> headerMapping;
+
     // the following objects are shared to reduce garbage
 
     /** A record buffer for getRecord(). Grows as necessary and is reused. */
@@ -78,7 +78,7 @@ public class CSVParser implements Iterable<String[]> {
      * @param input a Reader containing "csv-formatted" input
      * @throws IllegalArgumentException thrown if the parameters of the format are inconsistent
      */
-    public CSVParser(Reader input) {
+    public CSVParser(Reader input) throws IOException {
         this(input, CSVFormat.DEFAULT);
     }
 
@@ -89,14 +89,16 @@ public CSVParser(Reader input) {
      * @param format the CSVFormat used for CSV parsing
      * @throws IllegalArgumentException thrown if the parameters of the format are inconsistent
      */
-    public CSVParser(Reader input, CSVFormat format) {
+    public CSVParser(Reader input, CSVFormat format) throws IOException {
         format.validate();
 
         if (format.isUnicodeEscapesInterpreted()) {
             input = new UnicodeUnescapeReader(input);
         }
 
         this.lexer = new CSVLexer(format, new ExtendedBufferedReader(input));
+        
+        initializeHeader(format);
     }
 
     /**
@@ -106,7 +108,7 @@ public CSVParser(Reader input, CSVFormat format) {
      * @param format the CSVFormat used for CSV parsing
      * @throws IllegalArgumentException thrown if the parameters of the format are inconsistent
      */
-    public CSVParser(String input, CSVFormat format) {
+    public CSVParser(String input, CSVFormat format) throws IOException{
         this(new StringReader(input), format);
     }
 
@@ -120,15 +122,15 @@ public CSVParser(String input, CSVFormat format) {
      * @return matrix of records x values ('null' when end of file)
      * @throws IOException on parse error or input read-failure
      */
-    public String[][] getRecords() throws IOException {
-        List<String[]> records = new ArrayList<String[]>();
-        String[] record;
+    public List<CSVRecord> getRecords() throws IOException {
+        List<CSVRecord> records = new ArrayList<CSVRecord>();
+        CSVRecord record;
         while ((record = getRecord()) != null) {
             records.add(record);
         }
 
         if (!records.isEmpty()) {
-            return records.toArray(new String[records.size()][]);
+            return records;
         } else {
             return null;
         }
@@ -140,8 +142,8 @@ public String[][] getRecords() throws IOException {
      * @return the record as an array of values, or <tt>null</tt> if the end of the stream has been reached
      * @throws IOException on parse error or input read-failure
      */
-    String[] getRecord() throws IOException {
-        String[] result = EMPTY_STRING_ARRAY;
+    CSVRecord getRecord() throws IOException {
+        CSVRecord result = new CSVRecord(null, headerMapping);
         record.clear();
         do {
             reusableToken.reset();
@@ -161,25 +163,50 @@ String[] getRecord() throws IOException {
                     }
                     break;
                 case INVALID:
-                    // error: throw IOException
                     throw new IOException("(line " + getLineNumber() + ") invalid parse sequence");
-                    // unreachable: break;
             }
         } while (reusableToken.type == TOKEN);
 
         if (!record.isEmpty()) {
-            result = record.toArray(new String[record.size()]);
+            result = new CSVRecord(record.toArray(new String[record.size()]), headerMapping);
         }
         return result;
     }
 
+    /**
+     * Initializes the name to index mapping if the format defines a header.
+     */
+    private void initializeHeader(CSVFormat format) throws IOException {
+        if (format.getHeader() != null) {
+            headerMapping = new HashMap<String, Integer>();
+
+            String[] header = null;
+            if (format.getHeader().length == 0) {
+                // read the header from the first line of the file
+                CSVRecord record = getRecord();
+                if (record != null) {
+                    header = record.values();
+                }
+            } else {
+                header = format.getHeader();
+            }
+
+            // build the name to index mappings
+            if (header != null) {
+                for (int i = 0; i < header.length; i++) {
+                    headerMapping.put(header[i], i);
+                }
+            }
+        }
+    }
+
     /**
      * Returns an iterator on the records. IOExceptions occuring
      * during the iteration are wrapped in a RuntimeException.
      */
-    public Iterator<String[]> iterator() {
-        return new Iterator<String[]>() {
-            private String[] current;
+    public Iterator<CSVRecord> iterator() {
+        return new Iterator<CSVRecord>() {
+            private CSVRecord current;
 
             public boolean hasNext() {
                 if (current == null) {
@@ -189,8 +216,8 @@ public boolean hasNext() {
                 return current != null;
             }
 
-            public String[] next() {
-                String[] next = current;
+            public CSVRecord next() {
+                CSVRecord next = current;
                 current = null;
 
                 if (next == null) {
@@ -204,7 +231,7 @@ public String[] next() {
                 return next;
             }
 
-            private String[] getNextRecord() {
+            private CSVRecord getNextRecord() {
                 try {
                     return getRecord();
                 } catch (IOException e) {