1 package com.opencsv;
2
3 import com.opencsv.enums.CSVReaderNullFieldIndicator;
4
5 import java.io.IOException;
6 import java.util.Locale;
7
8 import static com.opencsv.enums.CSVReaderNullFieldIndicator.NEITHER;
9
10 /**
11 * This interface defines all of the behavior {@link com.opencsv.CSVReader}
12 * needs from a parser to tokenize an input line for further processing.
13 *
14 * @since 3.9
15 */
16 public interface ICSVParser {
17
18 /**
19 * The default separator to use if none is supplied to the constructor.
20 */
21 char DEFAULT_SEPARATOR = ',';
22
23 /**
24 * The average size of a line read by opencsv (used for setting the size of StringBuilders).
25 */
26 int INITIAL_READ_SIZE = 1024;
27
28 /**
29 * In most cases we know the size of the line we want to read. In that case we will set the initial read
30 * to that plus an buffer size.
31 */
32 int READ_BUFFER_SIZE = 128;
33
34 /**
35 * The default quote character to use if none is supplied to the
36 * constructor.
37 */
38 char DEFAULT_QUOTE_CHARACTER = '"';
39
40 /**
41 * The default escape character to use if none is supplied to the
42 * constructor.
43 */
44 char DEFAULT_ESCAPE_CHARACTER = '\\';
45
46 /**
47 * The default strict quote behavior to use if none is supplied to the
48 * constructor.
49 */
50 boolean DEFAULT_STRICT_QUOTES = false;
51
52 /**
53 * The default leading whitespace behavior to use if none is supplied to the
54 * constructor.
55 */
56 boolean DEFAULT_IGNORE_LEADING_WHITESPACE = true;
57
58 /**
59 * If the quote character is set to null then there is no quote character.
60 */
61 boolean DEFAULT_IGNORE_QUOTATIONS = false;
62
63 /**
64 * This is the "null" character - if a value is set to this then it is ignored.
65 */
66 char NULL_CHARACTER = '\0';
67
68 /**
69 * Denotes what field contents will cause the parser to return null: EMPTY_SEPARATORS, EMPTY_QUOTES, BOTH, NEITHER (default).
70 */
71 CSVReaderNullFieldIndicator DEFAULT_NULL_FIELD_INDICATOR = NEITHER;
72
73 /**
74 * The name of the resource bundle for translations of error messages in opencsv.
75 */
76 String DEFAULT_BUNDLE_NAME = "opencsv";
77
78 /**
79 * When creating builders this should be the smallest size to account for quotes and any possible escape characters.
80 */
81 int MAX_SIZE_FOR_EMPTY_FIELD = 16;
82
83 /**
84 * Default newline character for the parser.
85 */
86 String NEWLINE = "\n";
87
88 /**
89 * @return The default separator for this parser.
90 */
91 char getSeparator();
92
93 /**
94 * @return The default quotation character for this parser.
95 */
96 char getQuotechar();
97
98 /**
99 * @return True if something was left over from last call(s)
100 */
101 boolean isPending();
102
103 /**
104 * Parses an incoming String and returns an array of elements.
105 * This method is used when the data spans multiple lines.
106 *
107 * @param nextLine Current line to be processed
108 * @return The comma-tokenized list of elements, or null if nextLine is null
109 * @throws IOException If bad things happen during the read
110 */
111 String[] parseLineMulti(String nextLine) throws IOException;
112
113 /**
114 * Parses an incoming String and returns an array of elements.
115 * This method is used when all data is contained in a single line.
116 *
117 * @param nextLine Line to be parsed.
118 * @return The list of elements, or null if nextLine is null
119 * @throws IOException If bad things happen during the read
120 */
121 String[] parseLine(String nextLine) throws IOException;
122
123 /**
124 * Essentially a "Reverse parse" where an array of values are concatenating to a
125 * csv delimited string.
126 *
127 * @param values List of elements to parse.
128 * @param applyQuotesToAll - If true all strings in the array will have quotes if it needs it or not.
129 * If false then it will only have quotes if it needs it (i.e. contains a quote character).
130 * @return CSV formatted string representing the values in the array.
131 * @since 4.1
132 */
133 String parseToLine(String[] values, boolean applyQuotesToAll);
134
135 /**
136 * Essentially a "Reverse parse" where an array of values are concatenating to a
137 * csv delimited string.
138 * <p>
139 * NOTE: This functionality is for testing only in the 5.7.2 release in an effort to optimize the number of
140 * strings created when parsing large files.
141 *
142 * @param values List of elements to parse.
143 * @param applyQuotesToAll - If true all strings in the array will have quotes if it needs it or not.
144 * If false then it will only have quotes if it needs it (i.e. contains a quote character).
145 * @param appendable The Appendable that the parsed values will be appended to
146 * @since 5.7.2
147 */
148 void parseToLine(String[] values, boolean applyQuotesToAll, Appendable appendable) throws IOException;
149
150 /**
151 * @return The null field indicator.
152 */
153 CSVReaderNullFieldIndicator nullFieldIndicator();
154
155 /**
156 * If a parser is in the middle of parsing a multiline field, this will
157 * return the text collected so far.
158 *
159 * @return The incomplete text for a multiline field. If there is no
160 * pending text, this returns an empty string.
161 * @since 4.1
162 */
163 String getPendingText();
164
165 /**
166 * Sets the locale for all error messages.
167 * @param errorLocale Locale for error messages. If null, the default locale
168 * is used.
169 * @since 4.2
170 */
171 void setErrorLocale(Locale errorLocale);
172 }