001: /*
002: * Read files in comma separated value format.
003: * Copyright (C) 2002-2004 Stephen Ostermiller
004: * http://ostermiller.org/contact.pl?regarding=Java+Utilities
005: *
006: * This program is free software; you can redistribute it and/or modify
007: * it under the terms of the GNU General Public License as published by
008: * the Free Software Foundation; either version 2 of the License, or
009: * (at your option) any later version.
010: *
011: * This program is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: * GNU General Public License for more details.
015: *
016: * See COPYING.TXT for details.
017: */
018:
019: package com.Ostermiller.util;
020:
021: import java.io.*;
022:
023: /**
024: * Read files in comma separated value format.
025: * More information about this class is available from <a target="_top" href=
026: * "http://ostermiller.org/utils/CSVLexer.html">ostermiller.org</a>.
027: * This interface is designed to be set of general methods that all
028: * CSV parsers should implement.
029: *
030: * @author Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities
031: * @since ostermillerutils 1.00.00
032: */
033: public interface CSVParse {
034:
035: /**
036: * Read the next value from the file. The line number from
037: * which this value was taken can be obtained from getLastLineNumber().
038: *
039: * @return the next value or null if there are no more values.
040: * @throws IOException if an error occurs while reading.
041: *
042: * @since ostermillerutils 1.00.00
043: */
044: public String nextValue() throws IOException;
045:
046: /**
047: * Get the line number that the last token came from.
048: *
049: * @return line number or -1 if no tokens have been returned yet.
050: *
051: * @since ostermillerutils 1.00.00
052: */
053: public int lastLineNumber();
054:
055: /**
056: * Get all the values from a line.
057: * <p>
058: * If the line has already been partially read, only the
059: * values that have not already been read will be included.
060: *
061: * @return all the values from the line or null if there are no more values.
062: * @throws IOException if an error occurs while reading.
063: *
064: * @since ostermillerutils 1.00.00
065: */
066: public String[] getLine() throws IOException;
067:
068: /**
069: * Get the line number that the last token came from.
070: * <p>
071: * New line breaks that occur in the middle of a token are not
072: * counted in the line number count.
073: *
074: * @return line number or -1 if no tokens have been returned yet.
075: *
076: * @since ostermillerutils 1.00.00
077: */
078: public int getLastLineNumber();
079:
080: /**
081: * Get all the values from the file.
082: * <p>
083: * If the file has already been partially read, only the
084: * values that have not already been read will be included.
085: * <p>
086: * Each line of the file that has at least one value will be
087: * represented. Comments and empty lines are ignored.
088: * <p>
089: * The resulting double array may be jagged.
090: *
091: * @return all the values from the file or null if there are no more values.
092: * @throws IOException if an error occurs while reading.
093: *
094: * @since ostermillerutils 1.00.00
095: */
096: public String[][] getAllValues() throws IOException;
097:
098: /**
099: * Change this parser so that it uses a new delimiter.
100: * <p>
101: * The initial character is a comma, the delimiter cannot be changed
102: * to a quote or other character that has special meaning in CSV.
103: *
104: * @param newDelim delimiter to which to switch.
105: * @throws BadDelimiterException if the character cannot be used as a delimiter.
106: *
107: * @since ostermillerutils 1.02.08
108: */
109: public void changeDelimiter(char newDelim)
110: throws BadDelimiterException;
111:
112: /**
113: * Change this parser so that it uses a new character for quoting.
114: * <p>
115: * The initial character is a double quote ("), the delimiter cannot be changed
116: * to a comma or other character that has special meaning in CSV.
117: *
118: * @param newQuote character to use for quoting.
119: * @throws BadQuoteException if the character cannot be used as a quote.
120: *
121: * @since ostermillerutils 1.02.16
122: */
123: public void changeQuote(char newQuote) throws BadQuoteException;
124:
125: /**
126: * Close any stream upon which this parser is based.
127: *
128: * @since ostermillerutils 1.02.26
129: * @throws IOException if an error occurs while closing the stream.
130: */
131: public void close() throws IOException;
132:
133: }
|