001    /* LineNumberInputStream.java -- An input stream which counts line numbers
002       Copyright (C) 1998, 1999, 2002, 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    
039    package 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     */
072    public 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    }