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