OstermillerUtils
Documentation

Comma Separated Values (CSV)

Utilities for reading and writing CSV (comma separated value) text files.

The CSV parser classes take care of reading CSV files including: splitting out fields (even quoted and escaped fields), escaped data, line numbering, escape and comments. Each line of values can be returned as an array, or the values can be returned individually with the number of the line from which they came.

The CSV printer classes take care of writing CSV files including determining if the data needs to be escaped.

This utility supports two flavors of CSV:

  • UNIX style
    • backslash escape character for quotes (\"), new lines (\n), and backslashes (\)
    • Each record must be on its own line. If a field contains a new line, the new line must be escaped.
    • Leading and trailing white space on an unquoted field is ignored.
    • Compatible with standard unix text processing tools such as grep and sed that work on a line by line basis.
    • Reader: CSVParser, Writer: CSVPrinter
  • Microsoft Excel Style
    • Two quotes escape character ("" escapes "), no other characters are escaped.
    • Compatible with Microsoft Excel and many other programs that have adopted the format for data import and export.
    • Leading and trailing white space on an unquoted field is significant.
    • Specified by RFC4180.
    • Reader: ExcelCSVParser, Writer: ExcelCSVPrinter

Note that for simple field data that does not contain quotes or new lines, the two formats are fairly equivalent.

Labeled CSV Parser

Decorates either any flavor of CSV parser such that the first row read is a row of labels. Data in each row can be read by column name.

Example

LabeledCSVParser lcsvp = new LabeledCSVParser(
    new CSVParser(
        new StringReader(
            "Name,Phone\n" +
            "Stewart,212-555-3233\n" +
            "Cindy,212-555-8492\n"
        )
    )
);

while(lcsvp.getLine() != null){
    System.out.println(
        "Name: " + lcsvp.getValueByLabel("Name")
    );
    System.out.println(
        "Phone: " + lcsvp.getValueByLabel("Phone")
    );
}

CSV Parse (CSV Reader Interface)

Common interface for either the UNIX style CSV reader (CSVParser) or the Excel style CSV reader (ExcelCSVParser).

Example

CSVParse parser;

// UNIX style
parser = new CSVParser(System.in);

// Microsoft Excel style
parser = new ExcelCSVParser(System.in);

CSV Print (CSV Writer Interface)

Common interface for either the UNIX style CSV writer (CSVPrinter) or the Excel style CSV writer (ExcelCSVPrinter).

Example

CSVPrint printer;

// UNIX style
printer = new CSVPrinter(System.out);

// Microsoft Excel style
printer = new ExcelCSVPrinter(System.out);

CSV Printer (UNIX Style CSV Writer)

This class makes it easy to output CSV. Given values, it will automatically determine if they need to be quoted and escape special characters. Comments can easily be written and system appropriate line beginnings will be added.

Example

// Create the printer
CSVPrinter csvp = new CSVPrinter(
    System.out
);

// Write to the printer
csvp.writeln(
    new String[]{
        "hello","world"
    }
);

CSV Parser (UNIX Style CSV Reader)

This class makes it easy to input CSV. Given a stream, it will parse the stream and return the fields as strings, the lines as string arrays, or the whole file as a two dimensional string array.

Example

// Parse the data
String[][] values = CSVParser.parse(
    new StringReader(
        "hello,world\n" +
        "how,are,you"
    )
);

// Display the parsed data
for (int i=0; i<values.length; i++){
    for (int j=0; j<values[i].length; j++){
        System.out.println(values[i][j]);
    }
    System.out.println("-----");
}

Excel CSV Printer (Microsoft Excel Style CSV Writer)

Example

// Create the printer
ExcelCSVPrinter ecsvp = new ExcelCSVPrinter(
    System.out
);

// Write to the printer
ecsvp.writeln(
    new String[]{
        "hello","world"
    }
);

Excel CSV Parser (Microsoft Excel Style CSV Reader)

Example

// Parse the data
String[][] values = ExcelCSVParser.parse(
    new StringReader(
        "hello,world\n" +
        "how,are,you"
    )
);

// Display the parsed data
for (int i=0; i<values.length; i++){
    for (int j=0; j<values[i].length; j++){
        System.out.println(values[i][j]);
    }
    System.out.println("-----");
}

CSV Character Sets

Several people have asked how to read CSV files that are in other character sets such as Chinese or Japanese. To parse such files, use the parser constructor that takes a reader. Make sure the reader has been initialized to read the correct character set. The following example reads Simplified Chinese (charset GB2312) CSV values from CSVCharsetTest.gb2312csv If you have a Chinese font installed and Java is set up to use it, the example will show a dialog with each of the Chinese words on it.

Example

    CSVParser shredder = new CSVParser(
        new InputStreamReader(
            new FileInputStream("CSVCharsetTest.gb2312csv"),
            "GB2312"
        )
    );
    String t;
    while ((t = shredder.nextValue()) != null) {
        JOptionPane.showMessageDialog(
            null,
            t,
            "Value from line " + shredder.getLastLineNumber(),
            JOptionPane.INFORMATION_MESSAGE
        );
    }

CSV Lexer

The lexer (CSVLexer) created using JFlex is still available in the download and is still supported. In fact, CSVParser uses it behind the scenes. However, CSVParser has a much cleaner, full-featured API and its use is recommended.

Links

AuthorLicenseFeatures
Stephen Ostermiller ostermillerutils CSV and ExcelCSV for JavaOpen source, GPLParses CSV streams into Java Strings or arrays of Strings.
Bytecode Pty Ltd. opencsvOpen source, Apache licenceParses CSV files into Java Strings or arrays of Strings.
Ricebridge CSV Manager configured to parse standard CSV, Excel CSV, or other user specified variants.Commercial, with various license price points.Parses CSV streams with callback methods when data is found. Single CSV parsing class can be
E.Allen Soard Java CSV LibraryOpen source, LGPLParses CSV files into Java objects contained entirely in memory.
Nilo de Roock xlSQL Open source, GPLProvides a JDBC interface for accessing CSV files.
Bruce Dunwiddie CsvReader Commercial, with various license price points.Reads CSV files one line at a time and values may be obtained by name (similar to LabeledCSVParser) or by index. Single CSV parsing class can be configured to parse standard CSV, Excel CSV, or other user specified variants. A .Net version of the parser is also available.
Roedy Green Mindprod CSVOpen source, freeware (except military)CSV definition and libraries.