commons-csv/src/site/xdoc/user-guide.xml at trunk · ielatif/commons-csv · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>
 <properties>
  <title>User Guide</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>
<body>
<!-- ================================================== -->
<section name="Parsing an Excel CSV File">
  <p>To parse an Excel CSV file, write:</p>
  <source>Reader in = new FileReader(&quot;path/to/file.csv&quot;);
Iterable&lt;CSVRecord&gt; records = CSVFormat.EXCEL.parse(in);
for (CSVRecord record : records) {
    String lastName = record.get("Last Name");
    String firstName = record.get("First Name");
}</source>
</section>
<section name="Handling Byte Order Marks">
  <p>
    To handle files that start with a Byte Order Mark (BOM) like some Excel CSV files, you need an extra step to deal with these optional bytes.
    You can use the
    <a href="https://commons.apache.org/proper/commons-io/apidocs/org/apache/commons/io/input/BOMInputStream.html">BOMInputStream</a>
    class from <a href="https://commons.apache.org/proper/commons-io/">Apache Commons IO</a> for example:
  </p>
  <source>final URL url = ...;
final Reader reader = new InputStreamReader(new BOMInputStream(url.openStream()), "UTF-8");
final CSVParser parser = new CSVParser(reader, CSVFormat.EXCEL.withHeader());
try {
    for (final CSVRecord record : parser) {
        final String string = record.get("SomeColumn");
        ...
    }
} finally {
    parser.close();
    reader.close();
}</source>
  <p>
    You might find it handy to create something like this:
  </p>
  <source>/**
 * Creates a reader capable of handling BOMs.
 */
public InputStreamReader newReader(final InputStream inputStream) {
    return new InputStreamReader(new BOMInputStream(inputStream), StandardCharsets.UTF_8);
}</source>
</section>
<section name="Printing with headers">
  <p>
    To print a CSV file with headers, you specify the headers in the format:
  </p>
  <source>final Appendable out = ...;
final CSVPrinter printer = CSVFormat.DEFAULT.withHeader("H1", "H2").print(out)</source>
  <p>
    To print a CSV file with JDBC column labels, you specify the ResultSet in the format:
  </p>
  <source>final ResultSet resultSet = ...;
final CSVPrinter printer = CSVFormat.DEFAULT.withHeader(resultSet).print(out)</source>
</section>
<!-- ================================================== -->
</body>
</document>