Skip to content

Latest commit

 

History

History
151 lines (114 loc) · 4.88 KB

README.md

File metadata and controls

151 lines (114 loc) · 4.88 KB
Raw

picocsv - unusual CSV library for Java

Download Changes

Picocsv is an unusual CSV library designed to be embedded in other libraries.
While it can be used directly, it's main purpose is to be the core foundation of those other libraries.
For a more user-friendly CSV library, you should have a look at the fast and well-documented FastCSV library.

Key points:

  • lightweight library with no dependency
  • fast and efficient (no heap memory allocation)
  • designed to be embedded into other libraries as an external dependency or as a single-file source
  • has a module-info that makes it compatible with JPMS
  • Java 8 minimum requirement

Features:

  • reads/writes CSV from/to character streams
  • provides a minimalist low-level API
  • does not interpret content
  • does not correct invalid files
  • follows the RFC4180 specification
  • supports custom line separator
  • supports custom comment character

⚠️ Note that the Csv.Format#acceptMissingField option must be set to false to closely follow the RFC4180 specification. The default value is currently true but will be reversed in the next major release.

Examples

Read examples

Basic reading of all fields skipping comments:

try (java.io.Reader chars = ...; 
        Csv.Reader csv = Csv.Reader.of(Csv.Format.DEFAULT, Csv.ReaderOptions.DEFAULT, chars)) {
  while (csv.readLine()) {
    if (!csv.isComment()) {
      while (csv.readField()) {
        CharSequence field = csv;
        ...
      }
    }
  }
}

Configuring reading options:

Csv.ReaderOptions strict = Csv.ReaderOptions.builder().lenientSeparator(false).build();

Write examples

Basic writing of some fields and comments:

try (java.io.Writer chars = ...;
        Csv.Writer csv = Csv.Writer.of(Csv.Format.DEFAULT, Csv.WriterOptions.DEFAULT, chars)) {
  csv.writeComment("Some comment");
  csv.writeField("Some field");
  csv.writeEndOfLine();
}

Custom format

Csv.Format tsv = Csv.Format.builder().delimiter('\t').build();

Readable/Appendable

picocsv only supports java.io.Reader/java.io.Writer as input/output for performance reasons. However, it is still possible to use Readable/Appendable by wrapping them in adapters. See Cookbook#asCharReader(Readable) and Cookbook#asCharWriter(Appendable).

Disabling comments

Comments can be disabled by setting the Csv.Format#comment option to the null character \0.

Csv.Format noComment = Csv.Format.builder().comment('\0').build();

⚠️ Note that this might lead to problems since binary data is allowed in RFC-4180-bis. It will be fixed in a future release.

Skipping comments

Comments can be skipped by using the Csv.Reader#isComment() method.

while (csv.readLine()) {
    if (!csv.isComment()) {
        while (csv.readField()) { ... }
    }
}

Skipping empty lines

Empty lines are valid lines represented by a single empty field in RFC-4180.
However, it is still possible to skip them by using the Csv.Format#acceptMissingField option.

Csv.Format format = Csv.Format.builder().acceptMissingField(true).build();
try (Csv.Reader csv = ...) {
    while (csv.readLine()) {
        if (!csv.readField()) {
            continue; // line without field => empty line
        }
        do { ... } while (csv.readField());
    }
}

Setup

Maven setup:

<dependency>
    <groupId>com.github.nbbrd.picocsv</groupId>
    <artifactId>picocsv</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Developing

This project is written in Java and uses Apache Maven as a build tool.
It requires Java 8 as minimum version and all its dependencies are hosted on Maven Central.

The code can be build using any IDE or by just type-in the following commands in a terminal:

git clone https://github.com/nbbrd/picocsv.git
cd picocsv
mvn clean install

Contributing

Any contribution is welcome and should be done through pull requests and/or issues.

Licensing

The code of this project is licensed under the European Union Public Licence (EUPL).