1 /*
2 * CSVeed (https://github.com/42BV/CSVeed)
3 *
4 * Copyright 2013-2023 CSVeed.
5 *
6 * All rights reserved. This program and the accompanying materials
7 * are made available under the terms of The Apache Software License,
8 * Version 2.0 which accompanies this distribution, and is available at
9 * https://www.apache.org/licenses/LICENSE-2.0.txt
10 */
11 package org.csveed.row;
12
13 /**
14 * These instructions are used to power the {@link RowReader}. Note that the instructions are also used internally if
15 * annotations are used.
16 */
17 public interface RowInstructions {
18
19 /**
20 * Makes sure that the first readable line is interpreted as the header line. That line will not be read as content.
21 * This method is called whenever {@link org.csveed.annotations.CsvFile#useHeader()} is used. The default value for
22 * this setting is true.
23 *
24 * @param useHeader
25 * true if the header is interpreted and used
26 *
27 * @return convenience for chaining
28 */
29 RowInstructions setUseHeader(boolean useHeader);
30
31 /**
32 * Checks to see if a header must be used for the table.
33 *
34 * @return true if a header must be used
35 */
36 boolean isUseHeader();
37
38 /**
39 * Sets the start row of the CSV file. If {@link #setUseHeader(boolean)} == true, this will be the header row and
40 * the next ones are all content rows. This method is called whenever
41 * {@link org.csveed.annotations.CsvFile#startRow()} is used. The default value for this setting is 0.
42 *
43 * @param startRow
44 * the first row to start reading, including the header row
45 *
46 * @return convenience for chaining
47 */
48 RowInstructions setStartRow(int startRow);
49
50 /**
51 * Returns the escape character to use for writing a cell.
52 *
53 * @return the escape character
54 */
55 char getEscape();
56
57 /**
58 * Sets the character that will be interpreted as an escape symbol while within a quoted field. This method is
59 * called whenever {@link org.csveed.annotations.CsvFile#escape()} is used. The default value for this setting is a
60 * double quote (") symbol.
61 *
62 * @param symbol
63 * the symbol to use for escaping characters within a quoted field
64 *
65 * @return convenience for chaining
66 */
67 RowInstructions setEscape(char symbol);
68
69 /**
70 * Returns the character that will be used when writing quote characters.
71 *
72 * @return character used to represent quote characters
73 */
74 char getQuote();
75
76 /**
77 * Sets the character that will be interpreted as a quote symbol, signifying either the start or the end of a quoted
78 * field. This method is called whenever {@link org.csveed.annotations.CsvFile#quote()} is used. The default value
79 * for this setting is a double quote (") symbol.
80 *
81 * @param symbol
82 * the symbol to use for indicating start/end of a quoted field
83 *
84 * @return convenience for chaining
85 */
86 RowInstructions setQuote(char symbol);
87
88 /**
89 * Sets whether or not quotes are written around the field values. If enabled, the character set as the escape
90 * symbol will be disabled. If disabled, no quotes are written around the field values and the escape symbol is not
91 * escaped. This setting has <strong>no</strong> effect when reading CSV files, only when writing them.
92 *
93 * @param enabled
94 * whether or not to put quotes around fields
95 *
96 * @return convenience for chaining
97 */
98 RowInstructions setQuotingEnabled(boolean enabled);
99
100 /**
101 * Returns whether or not quotes around fields are enabled.
102 *
103 * @return true if quotes are enabled
104 */
105 boolean getQuotingEnabled();
106
107 /**
108 * Gets the character that will be used when writing separators.
109 *
110 * @return character used to represent separator characters
111 */
112 char getSeparator();
113
114 /**
115 * Sets the character that will be interpreted as a separator between cells. This method is called whenever
116 * {@link org.csveed.annotations.CsvFile#separator()} is used. The default value for this setting is a semi-colon
117 * (;).
118 *
119 * @param symbol
120 * the symbol to use as a separator between cells
121 *
122 * @return convenience for chaining
123 */
124 RowInstructions setSeparator(char symbol);
125
126 /**
127 * Sets the character that will be interpreted as a comment field on the first position of a row. This method is
128 * called whenever {@link org.csveed.annotations.CsvFile#comment()} is used. The default value for this setting is a
129 * hashtag (#).
130 *
131 * @param symbol
132 * the symbol to use as the 0-position comment marker
133 *
134 * @return convenience for chaining
135 */
136 RowInstructions setComment(char symbol);
137
138 /**
139 * Gets the characters that will be used when writing End-of-line separators.
140 *
141 * @return the EOL characters
142 */
143 char[] getEndOfLine();
144
145 /**
146 * Sets the characters (plural) that will be interpreted as end-of-line markers (unless within a quoted field). This
147 * method is called whenever {@link org.csveed.annotations.CsvFile#endOfLine()} is used. The default values for this
148 * setting are \r and \n
149 *
150 * @param symbols
151 * the symbol to interpret as end-of-line markers (unless within a quoted field)
152 *
153 * @return convenience for chaining
154 */
155 RowInstructions setEndOfLine(char[] symbols);
156
157 /**
158 * Determines whether empty lines must be skipped or treated as single-column rows. This method is called whenever
159 * {@link org.csveed.annotations.CsvFile#skipEmptyLines()} is used. The default value for this setting is to skip
160 * the empty lines.
161 *
162 * @param skip
163 * true to skip empty lines, false to treat as single-column rows
164 *
165 * @return convenience for chaining
166 */
167 RowInstructions skipEmptyLines(boolean skip);
168
169 /**
170 * Determines whether comment lines must be skipped. This method is called whenever
171 * {@link org.csveed.annotations.CsvFile#skipCommentLines()} is used. The default value for this setting is to skip
172 * comment lines. This method exists to guarantee that lines are not accidentally treated as comment lines.
173 *
174 * @param skip
175 * true to skip comment lines, identified as starting with a comment marker
176 *
177 * @return convenience for chaining
178 */
179 RowInstructions skipCommentLines(boolean skip);
180
181 }