libjava/java/io/LineNumberReader.java

   1 /* LineNumberReader.java -- A character input stream which counts line numbers
   2    Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.io;
  39
  40 /**
  41  * This class functions like a standard <code>Reader</code> except that it
  42  * counts line numbers, and canonicalizes newline characters.  As data
  43  * is read, whenever the char sequences "\r", "\n", or "\r\n" are encountered,
  44  * the running line count is incremeted by one.  Additionally, the whatever
  45  * line termination sequence was encountered will be converted to a "\n"
  46  * char.  Note that this class numbers lines from 0.  When the first
  47  * line terminator is encountered, the line number is incremented to 1, and
  48  * so on.  Also note that actual "\r" and "\n" characters are looked for.
  49  * The system dependent line separator sequence is ignored.
  50  * <p>
  51  * This class counts only line termination characters.  If the last line
  52  * read from the stream does not end in a line termination sequence, it
  53  * will not be counted as a line.
  54  *
  55  * @author Per Bothner <bothner@cygnus.com>
  56  * @author Aaron M. Renn (arenn@urbanophile.com)
  57  * @author Guilhem Lavaux <guilhem@kaffe.org>
  58  * @date December 28, 2003.
  59  */
  60 /* Written using "Java Class Libraries", 2nd edition, plus online
  61  * API docs for JDK 1.2 beta from http://www.javasoft.com.
  62  * Status:  Believed complete and correct.
  63  *
  64  * This implementation has the feature that if '\r' is read, it
  65  * does not look for a '\n', but immediately returns '\n'.
  66  * On the next read(), if a '\n' is read, it is skipped.
  67  * This has the advantage that we do not read (and hang) unnecessarily.
  68  *
  69  * This implementation is also minimal in the number of fields it uses.
  70  */
  71 public class LineNumberReader extends BufferedReader
  72 {
  73   /** The current line number. */
  74   private int lineNumber;
  75   /** Whether we already found a new line in the former call. */
  76   private boolean matchedNewLine;
  77   /** The saved line number when calling mark() */
  78   private int savedLineNumber;
  79
  80   /**
  81     * Create a new <code>LineNumberReader</code> that reads from the
  82     * specified subordinate <code>Reader</code>.  A default 8K char sized
  83     * buffer will be used for reads.
  84     *
  85     * @param in The subordinate <code>Reader</code> to read from
  86     */
  87   public LineNumberReader(Reader in)
  88   {
  89     super(in, DEFAULT_BUFFER_SIZE);
  90   }
  91
  92   /**
  93     * This method initializes a new <code>LineNumberReader</code> to read
  94     * from the specified subordinate <code>Reader</code> using the specified
  95     * read buffer size.
  96     *
  97     * @param in The subordinate <code>Reader</code> to read from
  98     * @param size The buffer size to use for reading
  99     */
 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 line_number 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 len 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