001/* LineNumberReader.java -- A character input stream which counts line numbers
002   Copyright (C) 1998, 1999, 2001, 2003, 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
038package java.io;
039
040/**
041 * This class functions like a standard <code>Reader</code> except that it
042 * counts line numbers, and canonicalizes newline characters.  As data
043 * is read, whenever the char sequences "\r", "\n", or "\r\n" are encountered,
044 * the running line count is incremeted by one.  Additionally, the whatever
045 * line termination sequence was encountered will be converted to a "\n"
046 * char.  Note that this class numbers lines from 0.  When the first
047 * line terminator is encountered, the line number is incremented to 1, and
048 * so on.  Also note that actual "\r" and "\n" characters are looked for.
049 * The system dependent line separator sequence is ignored.
050 * <p>
051 * This class counts only line termination characters.  If the last line
052 * read from the stream does not end in a line termination sequence, it
053 * will not be counted as a line.
054 *
055 * @author Per Bothner (bothner@cygnus.com)
056 * @author Aaron M. Renn (arenn@urbanophile.com)
057 * @author Guilhem Lavaux (guilhem@kaffe.org)
058 * @date December 28, 2003.
059 */
060/* Written using "Java Class Libraries", 2nd edition, plus online
061 * API docs for JDK 1.2 beta from http://www.javasoft.com.
062 * Status:  Believed complete and correct.
063 *
064 * This implementation has the feature that if '\r' is read, it
065 * does not look for a '\n', but immediately returns '\n'.
066 * On the next read(), if a '\n' is read, it is skipped.
067 * This has the advantage that we do not read (and hang) unnecessarily.
068 *
069 * This implementation is also minimal in the number of fields it uses.
070 */
071public class LineNumberReader extends BufferedReader
072{
073  /** The current line number. */
074  private int lineNumber;
075  /** Whether we already found a new line in the former call. */
076  private boolean matchedNewLine;
077  /** The saved line number when calling mark() */
078  private int savedLineNumber;
079
080  /**
081    * Create a new <code>LineNumberReader</code> that reads from the
082    * specified subordinate <code>Reader</code>.  A default 8K char sized
083    * buffer will be used for reads.
084    *
085    * @param in The subordinate <code>Reader</code> to read from
086    */
087  public LineNumberReader(Reader in)
088  {
089    super(in, DEFAULT_BUFFER_SIZE);
090  }
091
092  /**
093    * This method initializes a new <code>LineNumberReader</code> to read
094    * from the specified subordinate <code>Reader</code> using the specified
095    * read buffer size.
096    *
097    * @param in The subordinate <code>Reader</code> to read from
098    * @param size The buffer size to use for reading
099    */
100  public LineNumberReader(Reader in, int size)
101  {
102    super(in, size);
103  }
104
105  /**
106    * This method returns the current line number
107    *
108    * @return The current line number
109    */
110  public int getLineNumber()
111  {
112    return lineNumber;
113  }
114
115  /**
116    * This method sets the current line number to the specified value.
117    *
118    * @param lineNumber The new line number
119    */
120  public void setLineNumber(int lineNumber)
121  {
122    this.lineNumber = lineNumber;
123  }
124
125  /**
126    * This method marks a position in the input to which the stream can be
127    * "reset" char calling the <code>reset()</code> method.  The parameter
128    * <code>readlimit</code> is the number of chars that can be read from the
129    * stream after setting the mark before the mark becomes invalid.   For
130    * example, if <code>mark()</code> is called with a read limit of 10,
131    * then when
132    * 11 chars of data are read from the stream before the <code>reset()</code>
133    * method is called, then the mark is invalid and the stream object
134    * instance is not required to remember the mark.
135    * <p>
136    * In this class, this method will remember the current line number as well
137    * as the current position in the stream.  When the <code>reset()</code>
138    * method
139    * is called, the line number will be restored to the saved line number in
140    * addition to the stream position.
141    *
142    * @param readLimit The number of chars that can be read before the
143    * mark becomes invalid
144    *
145    * @exception IOException If an error occurs
146    */
147  public void mark(int readLimit) throws IOException
148  {
149    if (readLimit < 0)
150      throw new IllegalArgumentException("Read-ahead limit is negative");
151
152    synchronized (lock)
153      {
154        // This is basically the same as BufferedReader.mark.
155        // However, if the previous character was a '\r', we need to
156        // save that 'r', in case the next character is a '\n'.
157        if (pos + readLimit > limit)
158          {
159            int saveCR = matchedNewLine ? 1 : 0;
160            char[] old_buffer = buffer;
161            if (readLimit > limit)
162              buffer = new char[saveCR + readLimit];
163            int copy_start = pos - saveCR;
164            savedLineNumber = lineNumber;
165            limit -= copy_start;
166            System.arraycopy(old_buffer, copy_start, buffer, 0, limit);
167            pos = saveCR;
168          }
169        markPos = pos;
170      }
171  }
172
173  /**
174    * This method resets a stream to the point where the <code>mark()</code>
175    * method
176    * was called.  Any chars that were read after the mark point was set will
177    * be re-read during subsequent reads.
178    * <p>
179    * In this class, this method will also restore the line number that was
180    * current when the <code>mark()</code> method was called.
181    *
182    * @exception IOException If an error occurs
183    */
184  public void reset() throws IOException
185  {
186    synchronized (lock)
187      {
188        if (markPos < 0)
189          throw new IOException("mark never set or invalidated");
190        lineNumber = savedLineNumber;
191        pos = markPos;
192        matchedNewLine = (markPos > 0 && buffer[markPos-1] == '\r');
193      }
194  }
195
196  /**
197   * This private method fills the input buffer whatever pos is.
198   * Consequently pos should be checked before calling this method.
199   *
200   * @return the number of bytes actually read from the input stream or
201   * -1 if end of stream.
202   * @exception IOException If an error occurs.
203   */
204  private int fill() throws IOException
205  {
206    if (markPos >= 0 && limit == buffer.length)
207      markPos = -1;
208    if (markPos < 0)
209      pos = limit = 0;
210    int count = in.read(buffer, limit, buffer.length - limit);
211    if (count <= 0)
212      return -1;
213    limit += count;
214
215    return count;
216  }
217
218  /**
219    * This method reads an unsigned char from the input stream and returns it
220    * as an int in the range of 0-65535.  This method will return -1 if the
221    * end of the stream has been reached.
222    * <p>
223    * Note that if a line termination sequence is encountered (ie, "\r",
224    * "\n", or "\r\n") then that line termination sequence is converted to
225    * a single "\n" value which is returned from this method.  This means
226    * that it is possible this method reads two chars from the subordinate
227    * stream instead of just one.
228    * <p>
229    * Note that this method will block until a char of data is available
230    * to be read.
231    *
232    * @return The char read or -1 if end of stream
233    *
234    * @exception IOException If an error occurs
235    */
236  public int read() throws IOException
237  {
238    synchronized (lock)
239      {
240        skipRedundantLF();
241        if (pos >= limit && fill() < 0)
242          return -1;
243        char ch = buffer[pos++];
244        
245        if ((matchedNewLine = (ch == '\r')) || ch == '\n')
246          {
247            lineNumber++;
248            return '\n';
249          }
250        matchedNewLine = false;
251        return (int) ch;
252      }
253  }
254
255  /**
256    * This method reads chars from a stream and stores them into a caller
257    * supplied buffer.  It starts storing data at index <code>offset</code> into   
258    * the buffer and attemps to read <code>len</code> chars.  This method can
259    * return before reading the number of chars requested.  The actual number
260    * of chars read is returned as an int.  A -1 is returned to indicated the
261    * end of the stream.
262    * <p>
263    * This method will block until some data can be read.
264    * <p>
265    * Note that if a line termination sequence is encountered (ie, "\r",
266    * "\n", or "\r\n") then that line termination sequence is converted to
267    * a single "\n" value which is stored in the buffer.  Only a single
268    * char is counted towards the number of chars read in this case.
269    *
270    * @param buf The array into which the chars read should be stored
271    * @param offset The offset into the array to start storing chars
272    * @param count The requested number of chars to read
273    *
274    * @return The actual number of chars read, or -1 if end of stream
275    *
276    * @exception IOException If an error occurs.
277    * @exception NullPointerException If buf is null (in any case).
278    * @exception IndexOutOfBoundsException If buffer parameters (offset and
279    * count) lies outside of the buffer capacity.
280    */
281  public int read(char[] buf, int offset, int count) throws IOException
282  {
283    if (buf == null)
284      throw new NullPointerException();
285
286    if (offset + count > buf.length || offset < 0)
287      throw new IndexOutOfBoundsException();
288
289    if (count <= 0)
290      {
291        if (count < 0)
292          throw new IndexOutOfBoundsException();
293        return 0;
294      }
295
296    synchronized (lock)
297      {
298        if (pos >= limit && fill() < 0)
299          return -1;
300        
301        int start_offset = offset;
302        boolean matched = matchedNewLine;
303        
304        while (count-- > 0 && pos < limit)
305          {
306            char ch = buffer[pos++];
307            if (ch == '\r')
308              {
309                lineNumber++;
310                matched = true;
311              }
312            else if (ch == '\n' && !matched)
313              lineNumber++;
314            else
315              matched = false;
316
317            buf[offset++] = ch;
318          }
319
320        matchedNewLine = matched;
321        return offset - start_offset;
322      }
323  }
324
325  private void skipRedundantLF() throws IOException
326  {
327    if (pos > 0 && matchedNewLine)
328      {
329        if (pos < limit)
330          { // fast case
331            if (buffer[pos] == '\n')
332              pos++;
333          }
334        else
335          { // check whether the next buffer begins with '\n'.
336            // in that case kill the '\n'.
337            if (fill() <= 0)
338              return;
339            if (buffer[pos] == '\n')
340              pos++;
341          }
342        matchedNewLine = true;
343      }
344  }
345
346  /**
347    * This method reads a line of text from the input stream and returns
348    * it as a <code>String</code>.  A line is considered to be terminated
349    * by a "\r", "\n", or "\r\n" sequence, not by the system dependent line
350    * separator.
351    *
352    * @return The line read as a <code>String</code> or <code>null</code>
353    * if end of stream.
354    *
355    * @exception IOException If an error occurs
356    */
357  public String readLine() throws IOException
358  {
359    // BufferedReader.readLine already does this.  Shouldn't need to keep
360    // track of newlines (since the read method deals with this for us).
361    // But if the buffer is large, we may not call the read method at all
362    // and super.readLine can't increment lineNumber itself.
363    // Though it may seem kludgy, the safest thing to do is to save off
364    // lineNumber and increment it explicitly when we're done (iff we
365    // ended with a '\n' or '\r' as opposed to EOF).
366    //
367    // Also, we need to undo the special casing done by BufferedReader.readLine
368    // when a '\r' is the last char in the buffer.  That situation is marked
369    // by 'pos > limit'.
370    int tmpLineNumber = lineNumber;
371    skipRedundantLF();
372    String str = super.readLine();
373    if (pos > limit)
374      --pos;
375
376    // The only case where you mustn't increment the line number is you are
377    // at the EOS.
378    if (str != null)
379      lineNumber = tmpLineNumber + 1;
380
381    return str;
382  }
383
384  /**
385    * This method skips over characters in the stream.  This method will
386    * skip the specified number of characters if possible, but is not required
387    * to skip them all.  The actual number of characters skipped is returned.
388    * This method returns 0 if the specified number of chars is less than 1.
389    *
390    * @param count The specified number of chars to skip.
391    *
392    * @return The actual number of chars skipped.
393    *
394    * @exception IOException If an error occurs
395    */
396  public long skip (long count) throws IOException
397  {
398    if (count < 0)
399      throw new IllegalArgumentException("skip() value is negative");
400    if (count == 0)
401      return 0;
402
403    int skipped;
404    char[] buf = new char[1];
405
406    for (skipped = 0; skipped < count; skipped++)
407      {
408        int ch = read(buf, 0, 1);
409
410        if (ch < 0)
411          break;
412      }
413
414    return skipped;
415  }
416}
417