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 package net.sf.logdistiller.util.csv;
021
022 import java.io.*;
023
024 /**
025 * Read files in comma separated value format. More information about this class is available from <a target="_top"
026 * href= "http://ostermiller.org/utils/CSVLexer.html">ostermiller.org</a>. This interface is designed to be set of
027 * general methods that all CSV parsers should implement.
028 *
029 * @author Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities
030 * @since ostermillerutils 1.00.00
031 */
032 public interface CSVParse
033 {
034
035 /**
036 * Read the next value from the file. The line number from which this value was taken can be obtained from
037 * 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 * @since ostermillerutils 1.00.00
042 */
043 public String nextValue()
044 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 * @since ostermillerutils 1.00.00
051 */
052 public int lastLineNumber();
053
054 /**
055 * Get all the values from a line.
056 * <p>
057 * If the line has already been partially read, only the values that have not already been read will be included.
058 *
059 * @return all the values from the line or null if there are no more values.
060 * @throws IOException if an error occurs while reading.
061 * @since ostermillerutils 1.00.00
062 */
063 public String[] getLine()
064 throws IOException;
065
066 /**
067 * Get the line number that the last token came from.
068 * <p>
069 * New line breaks that occur in the middle of a token are not counted in the line number count.
070 *
071 * @return line number or -1 if no tokens have been returned yet.
072 * @since ostermillerutils 1.00.00
073 */
074 public int getLastLineNumber();
075
076 /**
077 * Get all the values from the file.
078 * <p>
079 * If the file has already been partially read, only the values that have not already been read will be included.
080 * <p>
081 * Each line of the file that has at least one value will be represented. Comments and empty lines are ignored.
082 * <p>
083 * The resulting double array may be jagged.
084 *
085 * @return all the values from the file or null if there are no more values.
086 * @throws IOException if an error occurs while reading.
087 * @since ostermillerutils 1.00.00
088 */
089 public String[][] getAllValues()
090 throws IOException;
091
092 /**
093 * Change this parser so that it uses a new delimiter.
094 * <p>
095 * The initial character is a comma, the delimiter cannot be changed to a quote or other character that has special
096 * meaning in CSV.
097 *
098 * @param newDelim delimiter to which to switch.
099 * @throws BadDelimiterException if the character cannot be used as a delimiter.
100 * @since ostermillerutils 1.02.08
101 */
102 public void changeDelimiter( char newDelim )
103 throws BadDelimiterException;
104
105 /**
106 * Change this parser so that it uses a new character for quoting.
107 * <p>
108 * The initial character is a double quote ("), the delimiter cannot be changed to a comma or other character that
109 * has special meaning in CSV.
110 *
111 * @param newQuote character to use for quoting.
112 * @throws BadQuoteException if the character cannot be used as a quote.
113 * @since ostermillerutils 1.02.16
114 */
115 public void changeQuote( char newQuote )
116 throws BadQuoteException;
117
118 /**
119 * Close any stream upon which this parser is based.
120 *
121 * @since ostermillerutils 1.02.26
122 * @throws IOException if an error occurs while closing the stream.
123 */
124 public void close()
125 throws IOException;
126
127 /**
128 * Get the number of chars that have been read from the beginning.
129 *
130 * @since added in LogDistiller
131 */
132 public int getLastCharCount();
133 }