001/* LineNumberInputStream.java -- An input stream which counts line numbers
002   Copyright (C) 1998, 1999, 2002, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.io;
040
041/**
042 * This class functions like a standard <code>InputStream</code>
043 * except that it counts line numbers, and canonicalizes newline
044 * characters.  As data is read, whenever the byte sequences "\r",
045 * "\n", or "\r\n" are encountered, the running line count is
046 * incremeted by one.  Additionally, the whatever line termination
047 * sequence was encountered will be converted to a "\n" byte.  Note
048 * that this class numbers lines from 0.  When the first line
049 * terminator is encountered, the line number is incremented to 1, and
050 * so on.
051 * <p>
052 * This class counts only line termination characters.  If the last line
053 * read from the stream does not end in a line termination sequence, it
054 * will not be counted as a line.
055 * <p>
056 * Note that since this class operates as a filter on an underlying
057 * stream, it has the same mark/reset functionality as the underlying
058 * stream.  The <code>mark()</code> and <code>reset()</code> methods
059 * in this class handle line numbers correctly.  Calling
060 * <code>reset()</code> resets the line number to the point at which
061 * <code>mark()</code> was called if the subordinate stream supports
062 * that functionality.
063 * <p>
064 * @deprecated This class is deprecated in favor if
065 * <code>LineNumberReader</code> because it operates on ASCII bytes
066 * instead of an encoded character stream.  This class is for backward
067 * compatibility only and should not be used in new applications.
068 *
069 * @author Aaron M. Renn (arenn@urbanophile.com)
070 * @author Warren Levy (warrenl@cygnus.com)
071 */
072public class LineNumberInputStream extends FilterInputStream
073{
074  /** The current line number. */
075  private int lineNumber = 0;
076
077  /** The line number when the stream was marked. */
078  private int markLineNumber = 0;
079
080  /** Flag to indicate a '\r' was just read so that an immediately
081   * subsequent '\n' can be ignored. */
082  private boolean justReadReturnChar = false;
083
084  /**
085   * Create a new <code>LineNumberInputStream</code> that reads from the
086   * specified subordinate <code>InputStream</code>
087   *
088   * @param in The subordinate <code>InputStream</code> to read from
089   */
090  public LineNumberInputStream(InputStream in)
091  {
092    super(in);
093  }
094
095  /**
096   * This method returns the number of bytes that can be read from the
097   * stream before the stream can block.  This method is tricky
098   * because the subordinate <code>InputStream</code> might return
099   * only "\r\n" characters, which are replaced by a single "\n"
100   * character by the <code>read()</code> method of this class.  So
101   * this method can only guarantee that <code>in.available() /
102   * 2</code> bytes can actually be read before blocking.  In
103   * practice, considerably more bytes might be read before blocking
104   * <p>
105   * Note that the stream may not block if additional bytes beyond the count
106   * returned by this method are read.
107   *
108   * @return The number of bytes that can be read before blocking could occur
109   *
110   * @exception IOException If an error occurs
111   */
112  public int available() throws IOException
113  {
114    // We can only guarantee half the characters that might be available
115    // without blocking because "\r\n" is treated as a single character.
116    return in.available() / 2;
117  }
118
119  /**
120   * This method returns the current line number
121   *
122   * @return The current line number
123   */
124  public int getLineNumber()
125  {
126    return lineNumber;
127  }
128
129  /**
130   * This method marks a position in the input to which the stream can
131   * be "reset" byte calling the <code>reset()</code> method.  The
132   * parameter <code>readlimit</code> is the number of bytes that can
133   * be read from the stream after setting the mark before the mark
134   * becomes invalid.  For example, if <code>mark()</code> is called
135   * with a read limit of 10, then when 11 bytes of data are read from
136   * the stream before the <code>reset()</code> method is called, then
137   * the mark is invalid and the stream object instance is not
138   * required to remember the mark.
139   * <p>
140   * In this class, this method will remember the current line number
141   * as well as the current position in the stream.  When the
142   * <code>reset()</code> method is called, the line number will be
143   * restored to the saved line number in addition to the stream
144   * position.
145   * <p>
146   * This method only works if the subordinate stream supports mark/reset
147   * functionality.
148   *
149   * @param readlimit The number of bytes that can be read before the
150   * mark becomes invalid
151   */
152  public void mark(int readlimit)
153  {
154    in.mark(readlimit);
155    markLineNumber = lineNumber;
156  }
157
158  /**
159   * This method reads an unsigned byte from the input stream and returns it
160   * as an int in the range of 0-255.  This method will return -1 if the
161   * end of the stream has been reached.
162   * <p>
163   * Note that if a line termination sequence is encountered (ie, "\r",
164   * "\n", or "\r\n") then that line termination sequence is converted to
165   * a single "\n" value which is returned from this method.  This means
166   * that it is possible this method reads two bytes from the subordinate
167   * stream instead of just one.
168   * <p>
169   * Note that this method will block until a byte of data is available
170   * to be read.
171   *
172   * @return The byte read or -1 if end of stream
173   *
174   * @exception IOException If an error occurs
175   */
176  public int read() throws IOException
177  {
178    // Treat "\r\n" as a single character.  A '\r' may have been read by
179    // a previous call to read so we keep an internal flag to avoid having
180    // to read ahead.
181
182    int ch = in.read();
183
184    if (ch == '\n')
185      if (justReadReturnChar)
186        {
187          ch = in.read();
188          justReadReturnChar = false;
189        }
190      else
191        lineNumber++;
192    else if (ch == '\r')
193      {
194        ch = '\n';
195        justReadReturnChar = true;
196        lineNumber++;
197      }
198    else
199      justReadReturnChar = false;
200
201    return ch;
202  }
203
204  /**
205   * This method reads bytes from a stream and stores them into a caller
206   * supplied buffer.  It starts storing data at index <code>offset</code> into
207   * the buffer and attemps to read <code>len</code> bytes.  This method can
208   * return before reading the number of bytes requested.  The actual number
209   * of bytes read is returned as an int.  A -1 is returned to indicated the
210   * end of the stream.
211   * <p>
212   * This method will block until some data can be read.
213   * <p>
214   * Note that if a line termination sequence is encountered (ie, "\r",
215   * "\n", or "\r\n") then that line termination sequence is converted to
216   * a single "\n" value which is stored in the buffer.  Only a single
217   * byte is counted towards the number of bytes read in this case.
218   *
219   * @param b The array into which the bytes read should be stored
220   * @param off The offset into the array to start storing bytes
221   * @param len The requested number of bytes to read
222   *
223   * @return The actual number of bytes read, or -1 if end of stream
224   *
225   * @exception IOException If an error occurs.
226   */
227  public int read(byte[] b, int off, int len) throws IOException
228  {
229    if (off < 0 || len < 0 || off + len > b.length)
230      throw new ArrayIndexOutOfBoundsException();
231
232    // This case always succeeds.
233    if (len == 0)
234      return 0;
235
236    // The simplest, though not necessarily the most time efficient thing
237    // to do is simply call read(void) len times.  Since this is a deprecated
238    // class, that should be ok.
239    final int origOff = off;
240    while (len-- > 0)
241      {
242        int ch = read();
243        if (ch < 0)
244          break;
245
246        b[off++] = (byte) ch;
247      }
248
249    // This is safe since we already know that some bytes were
250    // actually requested.
251    return off == origOff ? -1 : off - origOff;
252  }
253
254  /**
255   * This method resets a stream to the point where the
256   * <code>mark()</code> method was called.  Any bytes that were read
257   * after the mark point was set will be re-read during subsequent
258   * reads.
259   * <p>
260   * In this class, this method will also restore the line number that was
261   * current when the <code>mark()</code> method was called.
262   *  <p>
263   * This method only works if the subordinate stream supports mark/reset
264   * functionality.
265   *
266   * @exception IOException If an error occurs
267   */
268  public void reset() throws IOException
269  {
270    in.reset();
271    lineNumber = markLineNumber;
272    justReadReturnChar = false;
273  }
274
275  /**
276   * This method sets the current line number to the specified value.
277   *
278   * @param lineNumber The new line number
279   */
280  public void setLineNumber(int lineNumber)
281  {
282    this.lineNumber = lineNumber;
283  }
284
285  /**
286   * This method skips up to the requested number of bytes in the
287   * input stream.  The actual number of bytes skipped is returned.  If the
288   * desired number of bytes to skip is negative, no bytes are skipped.
289   *
290   * @param n requested number of bytes to skip.
291   *
292   * @return The actual number of bytes skipped.
293   *
294   * @exception IOException If an error occurs.
295   */
296  public long skip(long n) throws IOException
297  {
298    if (n <= 0)
299      return 0L;
300
301    final long origN = n;
302
303    do
304      {
305        int ch = read();
306        if (ch < 0)
307          break;
308        if (ch == '\n' || ch == '\r')
309          lineNumber++;
310      }
311    while (--n > 0);
312
313    return origN - n;
314  }
315}