Rename "encapsulator" to "quoteChar" so we have quoteChar and quotePolicy. Encapsulator makes me want to ask "encapsulate what"? fieldEncapsulator would be better but so verbose, quoteChar feels more to the point to me and provides symmetry with quotePolicy.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/csv/trunk@1398009 13f79535-47bb-0310-9956-ffa450edef68

Author: garydgregory

src/main/java/org/apache/commons/csv/CSVFormat.java

@@ -40,14 +40,14 @@ public class CSVFormat implements Serializable {
     private static final long serialVersionUID = 1L;
 
     private final char delimiter;
-    private final Character encapsulator;
+    private final Character quoteChar;
+    private final Quote quotePolicy;
     private final Character commentStart;
     private final Character escape;
     private final boolean ignoreSurroundingSpaces; // Should leading/trailing spaces be ignored around values?
     private final boolean ignoreEmptyLines;
     private final String lineSeparator; // for outputs
     private final String[] header;
-    private final Quote quotePolicy;
 
     /**
      * Starting format; used for creating other formats.
@@ -129,7 +129,7 @@ public class CSVFormat implements Serializable {
      *
      * @param delimiter
      *            the char used for value separation
-     * @param encapsulator
+     * @param quoteChar
      *            the char used as value encapsulation marker
      * @param quotePolicy 
      *            the quote policy
@@ -150,7 +150,7 @@ public CSVFormat(final char delimiter, final Character encapsulator, final Quote
                     boolean ignoreSurroundingSpaces, final boolean ignoreEmptyLines, final String lineSeparator, 
             final String[] header) {
         this.delimiter = delimiter;
-        this.encapsulator = encapsulator;
+        this.quoteChar = encapsulator;
         this.quotePolicy = quotePolicy;
         this.commentStart = commentStart;
         this.escape = escape;
@@ -178,8 +178,8 @@ private static boolean isLineBreak(final Character c) {
      * @throws IllegalStateException
      */
     void validate() throws IllegalStateException {
-        if (encapsulator != null && delimiter == encapsulator) {
-            throw new IllegalStateException("The encapsulator character and the delimiter cannot be the same ('" + encapsulator + "')");
+        if (quoteChar != null && delimiter == quoteChar) {
+            throw new IllegalStateException("The quoteChar character and the delimiter cannot be the same ('" + quoteChar + "')");
         }
 
         if (escape != null && delimiter == escape) {
@@ -191,8 +191,8 @@ void validate() throws IllegalStateException {
                     "')");
         }
 
-        if (encapsulator != null && encapsulator == commentStart) {
-            throw new IllegalStateException("The comment start character and the encapsulator cannot be the same ('" + commentStart + 
+        if (quoteChar != null && quoteChar == commentStart) {
+            throw new IllegalStateException("The comment start character and the quoteChar cannot be the same ('" + commentStart + 
                     "')");
         }
 
@@ -236,25 +236,25 @@ public CSVFormat withDelimiter(final Character delimiter) {
         if (isLineBreak(delimiter)) {
             throw new IllegalArgumentException("The delimiter cannot be a line break");
         }
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
     /**
      * Returns the character used to encapsulate values containing special characters.
      *
-     * @return the encapsulator character
+     * @return the quoteChar character
      */
-    public Character getEncapsulator() {
-        return encapsulator;
+    public Character getQuoteChar() {
+        return quoteChar;
     }
 
     /**
-     * Returns a copy of this format using the specified encapsulator character.
+     * Returns a copy of this format using the specified quoteChar character.
      *
-     * @param encapsulator
-     *            the encapsulator character
-     * @return A copy of this format using the specified encapsulator character
+     * @param quoteChar
+     *            the quoteChar character
+     * @return A copy of this format using the specified quoteChar character
      * @throws IllegalArgumentException
      *             thrown if the specified character is a line break
      */
@@ -263,29 +263,29 @@ public CSVFormat withEncapsulator(final char encapsulator) {
     }
 
     /**
-     * Returns a copy of this format using the specified encapsulator character.
+     * Returns a copy of this format using the specified quoteChar character.
      *
-     * @param encapsulator
-     *            the encapsulator character
-     * @return A copy of this format using the specified encapsulator character
+     * @param quoteChar
+     *            the quoteChar character
+     * @return A copy of this format using the specified quoteChar character
      * @throws IllegalArgumentException
      *             thrown if the specified character is a line break
      */
     public CSVFormat withEncapsulator(final Character encapsulator) {
         if (isLineBreak(encapsulator)) {
-            throw new IllegalArgumentException("The encapsulator cannot be a line break");
+            throw new IllegalArgumentException("The quoteChar cannot be a line break");
         }
         return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
     /**
-     * Returns whether an encapsulator has been defined.
+     * Returns whether an quoteChar has been defined.
      *
-     * @return {@code true} if an encapsulator is defined
+     * @return {@code true} if an quoteChar is defined
      */
     public boolean isEncapsulating() {
-        return encapsulator != null;
+        return quoteChar != null;
     }
 
     /**
@@ -327,7 +327,7 @@ public CSVFormat withCommentStart(final Character commentStart) {
         if (isLineBreak(commentStart)) {
             throw new IllegalArgumentException("The comment start character cannot be a line break");
         }
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
@@ -377,7 +377,7 @@ public CSVFormat withEscape(final Character escape) {
         if (isLineBreak(escape)) {
             throw new IllegalArgumentException("The escape character cannot be a line break");
         }
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
@@ -409,7 +409,7 @@ public boolean getIgnoreSurroundingSpaces() {
      * @return A copy of this format with the specified trimming behavior.
      */
     public CSVFormat withIgnoreSurroundingSpaces(final boolean ignoreSurroundingSpaces) {
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
@@ -432,7 +432,7 @@ public boolean getIgnoreEmptyLines() {
      * @return A copy of this format with the specified empty line skipping behavior.
      */
     public CSVFormat withIgnoreEmptyLines(final boolean ignoreEmptyLines) {
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
@@ -454,7 +454,7 @@ public String getLineSeparator() {
      * @return A copy of this format using the specified output line separator
      */
     public CSVFormat withLineSeparator(final char lineSeparator) {
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, String.valueOf(lineSeparator), header);
     }
 
@@ -467,7 +467,7 @@ public CSVFormat withLineSeparator(final char lineSeparator) {
      * @return A copy of this format using the specified output line separator
      */
     public CSVFormat withLineSeparator(final String lineSeparator) {
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
@@ -480,7 +480,7 @@ public CSVFormat withLineSeparator(final String lineSeparator) {
      * @return A copy of this format using the specified output line separator
      */
     public CSVFormat withQuotePolicy(final Quote quotePolicy) {
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
@@ -508,7 +508,7 @@ String[] getHeader() {
      * @return A copy of this format using the specified header
      */
     public CSVFormat withHeader(final String... header) {
-        return new CSVFormat(delimiter, encapsulator, quotePolicy, commentStart, escape,
+        return new CSVFormat(delimiter, quoteChar, quotePolicy, commentStart, escape,
                 ignoreSurroundingSpaces, ignoreEmptyLines, lineSeparator, header);
     }
 
@@ -549,7 +549,7 @@ public String toString() {
         }
         if (isEncapsulating()) {
             sb.append(' ');
-            sb.append("Encapsulator=<").append(encapsulator).append('>');
+            sb.append("Encapsulator=<").append(quoteChar).append('>');
         }
         if (isCommentingEnabled()) {
             sb.append(' ');

src/main/java/org/apache/commons/csv/CSVPrinter.java

@@ -201,7 +201,7 @@ void printAndEncapsulate(final CharSequence value, final int offset, final int l
         printDelimiter();
 
         final char delim = format.getDelimiter();
-        final char encapsulator = format.getEncapsulator();
+        final char encapsulator = format.getQuoteChar();
 
         if (len <= 0) {
             // always quote an empty token that is the first

src/main/java/org/apache/commons/csv/Lexer.java

@@ -57,7 +57,7 @@ abstract class Lexer {
         this.in = in;
         this.delimiter = format.getDelimiter();
         this.escape = mapNullToDisabled(format.getEscape());
-        this.encapsulator = mapNullToDisabled(format.getEncapsulator());
+        this.encapsulator = mapNullToDisabled(format.getQuoteChar());
         this.commmentStart = mapNullToDisabled(format.getCommentStart());
         this.ignoreSurroundingSpaces = format.getIgnoreSurroundingSpaces();
         this.ignoreEmptyLines = format.getIgnoreEmptyLines();

src/test/java/org/apache/commons/csv/CSVFormatTest.java

@@ -47,7 +47,7 @@ public void testImmutalibity() {
         format.withQuotePolicy(Quote.ALL);
 
         assertEquals('!', format.getDelimiter());
-        assertEquals('!', format.getEncapsulator().charValue());
+        assertEquals('!', format.getQuoteChar().charValue());
         assertEquals('!', format.getCommentStart().charValue());
         assertEquals('!', format.getEscape().charValue());
         assertEquals(CRLF, format.getLineSeparator());
@@ -63,7 +63,7 @@ public void testMutators() {
         final CSVFormat format = new CSVFormat('!', '!', null, '!', '!', true, true, CRLF, null);
 
         assertEquals('?', format.withDelimiter('?').getDelimiter());
-        assertEquals('?', format.withEncapsulator('?').getEncapsulator().charValue());
+        assertEquals('?', format.withEncapsulator('?').getQuoteChar().charValue());
         assertEquals('?', format.withCommentStart('?').getCommentStart().charValue());
         assertEquals("?", format.withLineSeparator("?").getLineSeparator());
         assertEquals('?', format.withEscape('?').getEscape().charValue());
@@ -171,7 +171,7 @@ public void testSerialization() throws Exception {
 
         assertNotNull(format);
         assertEquals("delimiter", CSVFormat.DEFAULT.getDelimiter(), format.getDelimiter());
-        assertEquals("encapsulator", CSVFormat.DEFAULT.getEncapsulator(), format.getEncapsulator());
+        assertEquals("encapsulator", CSVFormat.DEFAULT.getQuoteChar(), format.getQuoteChar());
         assertEquals("comment start", CSVFormat.DEFAULT.getCommentStart(), format.getCommentStart());
         assertEquals("line separator", CSVFormat.DEFAULT.getLineSeparator(), format.getLineSeparator());
         assertEquals("escape", CSVFormat.DEFAULT.getEscape(), format.getEscape());

src/test/java/org/apache/commons/csv/CSVLexer1.java

@@ -108,7 +108,7 @@ Token nextToken(Token tkn) throws IOException {
                 //noop: tkn.content.append("");
                 tkn.type = EORECORD;
                 tkn.isReady = true;
-            } else if (c == format.getEncapsulator()) {
+            } else if (c == format.getQuoteChar()) {
                 // consume encapsulated token
                 encapsulatedTokenLexer(tkn, c);
             } else if (isEndOfFile(c)) {
@@ -201,8 +201,8 @@ private Token encapsulatedTokenLexer(final Token tkn, int c) throws IOException
 
             if (c == format.getEscape()) {
                 tkn.content.append((char) readEscape());
-            } else if (c == format.getEncapsulator()) {
-                if (in.lookAhead() == format.getEncapsulator()) {
+            } else if (c == format.getQuoteChar()) {
+                if (in.lookAhead() == format.getQuoteChar()) {
                     // double or escaped encapsulator -> add single encapsulator to token
                     c = in.read();
                     tkn.content.append((char) c);