From 23898d62e2964c28531a9dd60c3263826d209814 Mon Sep 17 00:00:00 2001 From: Benedikt Ritter Date: Fri, 13 Sep 2013 11:01:28 +0000 Subject: [PATCH] Format JavaDoc git-svn-id: https://svn.apache.org/repos/asf/commons/proper/csv/trunk@1522865 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/commons/csv/CSVFormat.java | 69 +++++++++++++++---- 1 file changed, 57 insertions(+), 12 deletions(-) diff --git a/src/main/java/org/apache/commons/csv/CSVFormat.java b/src/main/java/org/apache/commons/csv/CSVFormat.java index 626a7055..5ad59a08 100644 --- a/src/main/java/org/apache/commons/csv/CSVFormat.java +++ b/src/main/java/org/apache/commons/csv/CSVFormat.java @@ -35,10 +35,13 @@ import java.util.Set; /** * Specifies the format of a CSV file and parses input. + * *

Using predefined formats

+ * *

* You can use one of the predefined formats: *

+ * * - *

For example:

- * 
CSVParser parser = CSVFormat.EXCEL.parse(reader);
- *

The {@link CSVRecord} provides static methods to parse other input types, for example:

+ * + *

+ * For example: + *

+ * + * 
+ * CSVParser parser = CSVFormat.EXCEL.parse(reader);
+ *
+ * + *

+ * The {@link CSVRecord} provides static methods to parse other input types, for example: + *

+ * * 
CSVParser parser = CSVFormat.parseFile(file, CSVFormat.EXCEL);
+ * *

Defining formats

+ * *

* You can extend a format by calling the {@code with} methods. For example: *

- * 
CSVFormat.EXCEL
+ *
+ * 
+ * CSVFormat.EXCEL
  *   .withNullString("N/A")
- *   .withIgnoreSurroundingSpaces(true);

+ *   .withIgnoreSurroundingSpaces(true);
+ *
+ * *

Defining column names

+ * *

* To define the column names you want to use to access records, write: *

- * 
CSVFormat.EXCEL.withHeader("Col1", "Col2", "Col3");
+ * + * 
+ * CSVFormat.EXCEL.withHeader("Col1", "Col2", "Col3");
+ *
+ * *

* Calling {@link #withHeader(String...)} let's you use the given names to address values in a {@link CSVRecord}, and - * assumes that your CSV source does not contain a first record that also defines column names. If it does, then - * you are overriding this metadata with your names and you should skip the first record by calling + * assumes that your CSV source does not contain a first record that also defines column names. + * + * If it does, then you are overriding this metadata with your names and you should skip the first record by calling * {@link #withSkipHeaderRecord(boolean)} with {@code true}. *

+ * *

Parsing

+ * *

* You can use a format directly to parse a reader. For example, to parse an Excel file with columns header, write: *

- * 
Reader in = ...;
- *CSVFormat.EXCEL.withHeader("Col1", "Col2", "Col3").parse(in);
+ * + * 
+ * Reader in = ...;
+ * CSVFormat.EXCEL.withHeader("Col1", "Col2", "Col3").parse(in);
+ *
+ * *

* For other input types, like resources, files, and URLs, use the static methods on {@link CSVParser}. *

+ * *

Referencing columns safely

+ * *

* If your source contains a header record, you can simplify your code and safely reference columns, * by using {@link #withHeader(String...)} with no arguments: *

- * 
CSVFormat.EXCEL.withHeader();
+ * + * 
+ * CSVFormat.EXCEL.withHeader();
+ *
+ * *

* This causes the parser to read the first record and use its values as column names. + * * Then, call one of the {@link CSVRecord} get method that takes a String column name argument: *

- * 
String value = record.get("Col1");
+ * + * 
+ * String value = record.get("Col1");
+ *
+ * *

* This makes your code impervious to changes in column order in the CSV file. *

+ * *

Notes

+ * *

* This class is immutable. *

+ * * @version $Id$ */ public class CSVFormat implements Serializable {