001    /* LineNumberReader.java -- A character input stream which counts line numbers
002       Copyright (C) 1998, 1999, 2001, 2003, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath 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, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package 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     */
071    public 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    }