Apache
/
commons-csv
mirror of https://github.com/apache/commons-csv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated the Javadoc 

git-svn-id: https://svn.apache.org/repos/asf/commons/sandbox/csv/trunk@1297043 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Emmanuel Bourg 2012-03-05 13:08:19 +00:00
parent 312f5b033e
commit 7bd9d1d970
3 changed files with 41 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/main/java/org/apache/commons/csv/CSVFormat.java
View File

@ -46,7 +46,7 @@ public class CSVFormat implements Cloneable, Serializable {
*/ */
public static final char DISABLED = '\ufffe'; public static final char DISABLED = '\ufffe';
/** Standard comma separated format as defined by RFC 4180. */ /** Standard comma separated format as defined by <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>. */
public static final CSVFormat DEFAULT = new CSVFormat(',', '"', DISABLED, DISABLED, true, true, false, true); public static final CSVFormat DEFAULT = new CSVFormat(',', '"', DISABLED, DISABLED, true, true, false, true);
/** Excel file format (using a comma as the value delimiter). */ /** Excel file format (using a comma as the value delimiter). */
@ -57,26 +57,33 @@ public class CSVFormat implements Cloneable, Serializable {
/** /**
* Creates a CSVFormat with the default parameters. * Creates a CSV format with the default parameters.
*/ */
public CSVFormat() { public CSVFormat() {
} }
/**
* Creates a customized CSV format.
*
* @param delimiter the char used for value separation
* @param encapsulator the char used as value encapsulation marker
* @param commentStart the char used for comment identification
*/
public CSVFormat(char delimiter, char encapsulator, char commentStart) { public CSVFormat(char delimiter, char encapsulator, char commentStart) {
this(delimiter, encapsulator, commentStart, DISABLED, true, true, false, true); this(delimiter, encapsulator, commentStart, DISABLED, true, true, false, true);
} }
/** /**
* Customized CSV format constructor. * Creates a customized CSV format.
* *
* @param delimiter a char used for value separation * @param delimiter the char used for value separation
* @param encapsulator a char used as value encapsulation marker * @param encapsulator the char used as value encapsulation marker
* @param commentStart a char used for comment identification * @param commentStart the char used for comment identification
* @param escape a char used to escape special characters in values * @param escape the char used to escape special characters in values
* @param leadingSpacesIgnored TRUE when leading whitespaces should be ignored * @param leadingSpacesIgnored <tt>true</tt> when leading whitespaces should be ignored
* @param trailingSpacesIgnored TRUE when trailing whitespaces should be ignored * @param trailingSpacesIgnored <tt>true</tt> when trailing whitespaces should be ignored
* @param unicodeEscapesInterpreted TRUE when unicode escapes should be interpreted * @param unicodeEscapesInterpreted <tt>true</tt> when unicode escapes should be interpreted
* @param emptyLinesIgnored TRUE when the parser should skip emtpy lines * @param emptyLinesIgnored <tt>true</tt> when the parser should skip emtpy lines
*/ */
public CSVFormat( public CSVFormat(
char delimiter, char delimiter,

46
src/main/java/org/apache/commons/csv/CSVParser.java
View File

@ -64,15 +64,14 @@ public class CSVParser implements Iterable<String[]> {
/** Immutable empty String array. */ /** Immutable empty String array. */
private static final String[] EMPTY_STRING_ARRAY = new String[0]; private static final String[] EMPTY_STRING_ARRAY = new String[0];
// the input stream /** The input stream */
private final ExtendedBufferedReader in; private final ExtendedBufferedReader in;
private final CSVFormat format; private final CSVFormat format;
// the following objects are shared to reduce garbage // the following objects are shared to reduce garbage
/**
* A record buffer for getLine(). Grows as necessary and is reused. /** A record buffer for getLine(). Grows as necessary and is reused. */
*/
private final List<String> record = new ArrayList<String>(); private final List<String> record = new ArrayList<String>();
private final Token reusableToken = new Token(); private final Token reusableToken = new Token();
private final CharBuffer wsBuf = new CharBuffer(); private final CharBuffer wsBuf = new CharBuffer();
@ -146,12 +145,10 @@ public class CSVParser implements Iterable<String[]> {
// ====================================================== // ======================================================
/** /**
* Parses the CSV according to the given format * Parses the CSV according to the given format and returns the content
* and returns the content as an array of records * as an array of records (whereas records are arrays of single values).
* (whereas records are arrays of single values).
* <p/> * <p/>
* The returned content starts at the current parse-position in * The returned content starts at the current parse-position in the stream.
* the stream.
* *
* @return matrix of records x values ('null' when end of file) * @return matrix of records x values ('null' when end of file)
* @throws IOException on parse error or input read-failure * @throws IOException on parse error or input read-failure
@ -171,11 +168,9 @@ public class CSVParser implements Iterable<String[]> {
} }
/** /**
* Parses from the current point in the stream til * Parses from the current point in the stream til * the end of the current line.
* the end of the current line.
* *
* @return array of values til end of line * @return array of values til end of line ('null' when end of file has been reached)
* ('null' when end of file has been reached)
* @throws IOException on parse error or input read-failure * @throws IOException on parse error or input read-failure
*/ */
String[] getLine() throws IOException { String[] getLine() throws IOException {
@ -209,7 +204,7 @@ public class CSVParser implements Iterable<String[]> {
} }
} }
if (!record.isEmpty()) { if (!record.isEmpty()) {
ret = (String[]) record.toArray(new String[record.size()]); ret = record.toArray(new String[record.size()]);
} }
return ret; return ret;
} }
@ -283,11 +278,9 @@ public class CSVParser implements Iterable<String[]> {
/** /**
* Returns the next token. * Returns the next token.
* <p/> * <p/>
* A token corresponds to a term, a record change or an * A token corresponds to a term, a record change or an end-of-file indicator.
* end-of-file indicator.
* *
* @param tkn an existing Token object to reuse. The caller is responsible to initialize the * @param tkn an existing Token object to reuse. The caller is responsible to initialize the Token.
* Token.
* @return the next token found * @return the next token found
* @throws IOException on stream access error * @throws IOException on stream access error
*/ */
@ -476,19 +469,13 @@ public class CSVParser implements Iterable<String[]> {
return tkn; return tkn;
} else if (!isWhitespace(c)) { } else if (!isWhitespace(c)) {
// error invalid char between token and next delimiter // error invalid char between token and next delimiter
throw new IOException( throw new IOException("(line " + getLineNumber() + ") invalid char between encapsulated token and delimiter");
"(line " + getLineNumber()
+ ") invalid char between encapsulated token end delimiter"
);
} }
} }
} }
} else if (isEndOfFile(c)) { } else if (isEndOfFile(c)) {
// error condition (end of file before end of token) // error condition (end of file before end of token)
throw new IOException( throw new IOException("(startline " + startLineNumber + ") EOF reached before encapsulated token finished");
"(startline " + startLineNumber + ")"
+ "eof reached before encapsulated token finished"
);
} else { } else {
// consume character // consume character
tkn.content.append((char) c); tkn.content.append((char) c);
@ -500,8 +487,7 @@ public class CSVParser implements Iterable<String[]> {
/** /**
* Decodes Unicode escapes. * Decodes Unicode escapes.
* <p/> * <p/>
* Interpretation of "\\uXXXX" escape sequences * Interpretation of "\\uXXXX" escape sequences where XXXX is a hex-number.
* where XXXX is a hex-number.
* *
* @param c current char which is discarded because it's the "\\" of "\\uXXXX" * @param c current char which is discarded because it's the "\\" of "\\uXXXX"
* @return the decoded character * @return the decoded character
@ -555,10 +541,6 @@ public class CSVParser implements Iterable<String[]> {
return out; return out;
} }
// ======================================================
// strategies
// ======================================================
/** /**
* Obtain the specified CSV format. * Obtain the specified CSV format.
* *

10
src/main/java/org/apache/commons/csv/package.html
View File

@ -35,7 +35,7 @@
record := values* record := values*
</pre> </pre>
<p>The following list contains the csv aspects the WAKE CSV parser supports:</p> <p>The following list contains the csv aspects the Commons CSV parser supports:</p>
<dl> <dl>
<dt>Separators (for lines)</dt> <dt>Separators (for lines)</dt>
<dd>The record separators are hardcoded and cannot be changed. The must be '\n' or '\r\n'.</dd> <dd>The record separators are hardcoded and cannot be changed. The must be '\n' or '\r\n'.</dd>
@ -76,9 +76,11 @@
<p>Example usage:</p> <p>Example usage:</p>
<blockquote><pre> <blockquote><pre>
String[] parsedLine = CSVParser.parseLine("a,b,c"); Reader in = new StringReader("a,b,c");
for (int i = 0; i &lt; parsedLine.length; ++i) { for (String[] line : CSVFormat.DEFAULT.parse(in)) {
System.out.println("value " + i + "=" + parsedLine[i]); for (int i = 0; i &lt; line.length; i++) {
System.out.println("value " + i + "=" + line[i]);
}
} }
</pre></blockquote> </pre></blockquote>
</body> </body>