Package org.apache.commons.csv

Class CSVParser

java.lang.Object
org.apache.commons.csv.CSVParser
All Implemented Interfaces:
Closeable, AutoCloseable, Iterable<CSVRecord>
public final class CSVParser extends Object implements Iterable<CSVRecord>, Closeable
Parses CSV files according to the specified format. Because CSV appears in many different dialects, the parser supports many formats by allowing the specification of a CSVFormat. The parser works record wise. It is not possible to go back, once a record has been parsed from the input stream.

Creating instances

There are several static factory methods that can be used to create instances for various types of resources:

Alternatively parsers can also be created by passing a Reader directly to the sole constructor. For those who like fluent APIs, parsers can be created using CSVFormat.parse(java.io.Reader) as a shortcut: 

 for(CSVRecord record : CSVFormat.EXCEL.parse(in)) {
     ...
 }

Parsing record wise

To parse a CSV input from a file, you write: 

 File csvData = new File("/path/to/csv");
 CSVParser parser = CSVParser.parse(csvData, CSVFormat.RFC4180);
 for (CSVRecord csvRecord : parser) {
     ...
 }

This will read the parse the contents of the file using the RFC 4180 format.

To parse CSV input in a format like Excel, you write: 

 CSVParser parser = CSVParser.parse(csvData, CSVFormat.EXCEL);
 for (CSVRecord csvRecord : parser) {
     ...
 }

If the predefined formats don't match the format at hands, custom formats can be defined. More information about customising CSVFormats is available in CSVFormat Javadoc.

Parsing into memory

If parsing record wise is not desired, the contents of the input can be read completely into memory. 

 Reader in = new StringReader("a;b\nc;d");
 CSVParser parser = new CSVParser(in, CSVFormat.EXCEL);
 List<CSVRecord> list = parser.getRecords();

There are two constraints that have to be kept in mind:

  1. Parsing into memory starts at the current position of the parser. If you have already parsed records from the input, those records will not end up in the in memory representation of your CSV data.
  2. Parsing into memory may consume a lot of system resources depending on the input. For example if you're parsing a 150MB file of CSV data the contents will be read completely into memory.

Notes

Internal parser state is completely covered by the format and the reader-state.

See Also:

  • Field Details

    • format

      private final CSVFormat format

    • headers

      private final CSVParser.Headers headers

    • lexer

      private final Lexer lexer

    • csvRecordIterator

      private final CSVParser.CSVRecordIterator csvRecordIterator

    • recordList

      private final List<String> recordList
      A record buffer for getRecord(). Grows as necessary and is reused.

    • recordNumber

      private long recordNumber
      The next record number to assign.

    • characterOffset

      private final long characterOffset
      Lexer offset when the parser does not start parsing at the beginning of the source. Usually used in combination with recordNumber.

    • reusableToken

      private final Token reusableToken

  • Constructor Details

    • CSVParser

      public CSVParser(Reader reader, CSVFormat format) throws IOException
      Customized CSV parser using the given CSVFormat

      If you do not read all records from the given reader, you should call close() on the parser, unless you close the reader.

      Parameters:
      reader - a Reader containing CSV-formatted input. Must not be null.
      format - the CSVFormat used for CSV parsing. Must not be null.
      Throws:
      IllegalArgumentException - If the parameters of the format are inconsistent or if either reader or format are null.
      IOException - If there is a problem reading the header or skipping the first record

    • CSVParser

      public CSVParser(Reader reader, CSVFormat format, long characterOffset, long recordNumber) throws IOException
      Customized CSV parser using the given CSVFormat

      If you do not read all records from the given reader, you should call close() on the parser, unless you close the reader.

      Parameters:
      reader - a Reader containing CSV-formatted input. Must not be null.
      format - the CSVFormat used for CSV parsing. Must not be null.
      characterOffset - Lexer offset when the parser does not start parsing at the beginning of the source.
      recordNumber - The next record number to assign
      Throws:
      IllegalArgumentException - If the parameters of the format are inconsistent or if either reader or format are null.
      IOException - If there is a problem reading the header or skipping the first record
      Since:
      1.1

  • Method Details

    • parse

      public static CSVParser parse(File file, Charset charset, CSVFormat format) throws IOException
      Creates a parser for the given File.
      Parameters:
      file - a CSV file. Must not be null.
      charset - The Charset to decode the given file.
      format - the CSVFormat used for CSV parsing. Must not be null.
      Returns:
      a new parser
      Throws:
      IllegalArgumentException - If the parameters of the format are inconsistent or if either file or format are null.
      IOException - If an I/O error occurs

    • parse

      public static CSVParser parse(InputStream inputStream, Charset charset, CSVFormat format) throws IOException
      Creates a CSV parser using the given CSVFormat.

      If you do not read all records from the given reader, you should call close() on the parser, unless you close the reader.

      Parameters:
      inputStream - an InputStream containing CSV-formatted input. Must not be null.
      charset - The Charset to decode the given file.
      format - the CSVFormat used for CSV parsing. Must not be null.
      Returns:
      a new CSVParser configured with the given reader and format.
      Throws:
      IllegalArgumentException - If the parameters of the format are inconsistent or if either reader or format are null.
      IOException - If there is a problem reading the header or skipping the first record
      Since:
      1.5

    • parse

      public static CSVParser parse(Path path, Charset charset, CSVFormat format) throws IOException
      Creates and returns a parser for the given Path, which the caller MUST close.
      Parameters:
      path - a CSV file. Must not be null.
      charset - The Charset to decode the given file.
      format - the CSVFormat used for CSV parsing. Must not be null.
      Returns:
      a new parser
      Throws:
      IllegalArgumentException - If the parameters of the format are inconsistent or if either file or format are null.
      IOException - If an I/O error occurs
      Since:
      1.5

    • parse

      public static CSVParser parse(Reader reader, CSVFormat format) throws IOException
      Creates a CSV parser using the given CSVFormat

      If you do not read all records from the given reader, you should call close() on the parser, unless you close the reader.

      Parameters:
      reader - a Reader containing CSV-formatted input. Must not be null.
      format - the CSVFormat used for CSV parsing. Must not be null.
      Returns:
      a new CSVParser configured with the given reader and format.
      Throws:
      IllegalArgumentException - If the parameters of the format are inconsistent or if either reader or format are null.
      IOException - If there is a problem reading the header or skipping the first record
      Since:
      1.5

    • parse

      public static CSVParser parse(String string, CSVFormat format) throws IOException
      Creates a parser for the given String.
      Parameters:
      string - a CSV string. Must not be null.
      format - the CSVFormat used for CSV parsing. Must not be null.
      Returns:
      a new parser
      Throws:
      IllegalArgumentException - If the parameters of the format are inconsistent or if either string or format are null.
      IOException - If an I/O error occurs

    • parse

      public static CSVParser parse(URL url, Charset charset, CSVFormat format) throws IOException
      Creates and returns a parser for the given URL, which the caller MUST close.

      If you do not read all records from the given url, you should call close() on the parser, unless you close the url.

      Parameters:
      url - a URL. Must not be null.
      charset - the charset for the resource. Must not be null.
      format - the CSVFormat used for CSV parsing. Must not be null.
      Returns:
      a new parser
      Throws:
      IllegalArgumentException - If the parameters of the format are inconsistent or if either url, charset or format are null.
      IOException - If an I/O error occurs

    • addRecordValue

      private void addRecordValue(boolean lastRecord)

    • close

      public void close() throws IOException
      Closes resources.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - If an I/O error occurs

    • createEmptyHeaderMap

      private Map<String,Integer> createEmptyHeaderMap()

    • createHeaders

      private CSVParser.Headers createHeaders() throws IOException
      Creates the name to index mapping if the format defines a header.
      Returns:
      null if the format has no header.
      Throws:
      IOException - if there is a problem reading the header or skipping the first record

    • getCurrentLineNumber

      public long getCurrentLineNumber()
      Returns the current line number in the input stream.

      ATTENTION: If your CSV input has multi-line values, the returned number does not correspond to the record number.

      Returns:
      current line number

    • getFirstEndOfLine

      public String getFirstEndOfLine()
      Gets the first end-of-line string encountered.
      Returns:
      the first end-of-line string
      Since:
      1.5

    • getHeaderMap

      public Map<String,Integer> getHeaderMap()
      Returns a copy of the header map.

      The map keys are column names. The map values are 0-based indices.

      Note: The map can only provide a one-to-one mapping when the format did not contain null or duplicate column names.

      Returns:
      a copy of the header map.

    • getHeaderMapRaw

      Map<String,Integer> getHeaderMapRaw()
      Returns the header map.
      Returns:
      the header map.

    • getHeaderNames

      public List<String> getHeaderNames()
      Returns a read-only list of header names that iterates in column order.

      Note: The list provides strings that can be used as keys in the header map. The list will not contain null column names if they were present in the input format.

      Returns:
      read-only list of header names that iterates in column order.
      Since:
      1.7
      See Also:

    • getRecordNumber

      public long getRecordNumber()
      Returns the current record number in the input stream.

      ATTENTION: If your CSV input has multi-line values, the returned number does not correspond to the line number.

      Returns:
      current record number

    • getRecords

      public List<CSVRecord> getRecords() throws IOException
      Parses the CSV input according to the given format and returns the content as a list of CSVRecords.

      The returned content starts at the current parse-position in the stream.

      Returns:
      list of CSVRecords, may be empty
      Throws:
      IOException - on parse error or input read-failure

    • handleNull

      private String handleNull(String input)
      Handle whether input is parsed as null
      Parameters:
      input - the cell data to further processed
      Returns:
      null if input is parsed as null, or input itself if input isn't parsed as null

    • isClosed

      public boolean isClosed()
      Tests whether this parser is closed.
      Returns:
      whether this parser is closed.

    • isStrictQuoteMode

      private boolean isStrictQuoteMode()
      Tests whether the format's QuoteMode is QuoteMode.ALL_NON_NULL or QuoteMode.NON_NUMERIC.
      Returns:
      true if the format's QuoteMode is QuoteMode.ALL_NON_NULL or QuoteMode.NON_NUMERIC.

    • iterator

      public Iterator<CSVRecord> iterator()
      Returns the record iterator.

      An IOException caught during the iteration are re-thrown as an IllegalStateException.

      If the parser is closed a call to Iterator.next() will throw a NoSuchElementException.

      Specified by:
      iterator in interface Iterable<CSVRecord>

    • nextRecord

      CSVRecord nextRecord() throws IOException
      Parses the next record from the current point in the stream.
      Returns:
      the record as an array of values, or null if the end of the stream has been reached
      Throws:
      IOException - on parse error or input read-failure

    • stream

      public Stream<CSVRecord> stream()
      Returns a sequential Stream with this collection as its source.
      Returns:
      a sequential Stream with this collection as its source.
      Since:
      1.9.0