IncludeReader (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.io

## Class IncludeReader

- java.lang.Object
- - java.io.Reader
  - - hlt.language.io.IncludeReader

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.lang.Readable

      public class IncludeReader
      extends java.io.Reader

  This class implements a Reader that may include another Reader in midstream reading, and eventually resume reading at that point upon reaching EOF in the included Reader.

  By default, included readers are read seamlessly. That is, when starting or ending an inclusion, the next character is that which starts the included reader or the next one in the enclosing reader. Inclusion seams may or not be made visible with `setSeamless(boolean)`. Called with `false` on an `IncludeReader` object, it will make its `read()` return `IO.SOI` ('start of input') or `IO.EOI` ('end of input'), both `int` constants, when starting or ending, respectively, reading an inclusion. Calling it with `true` re/sets seamless reading.

  NB: It is possible to prevent circular inclusions, although not in all situations. Indeed there is no way, in general, for an arbitary Reader to be identified as reading from a source being actively included. However, this can be done for `IncludeReader`s constructed from file readers by using the `IncludeReader(String)` constructor and the `include(String)` method, which provide identifiable file names. For file readers included using this constructor and method, any circular inclusion will be detected and cause a `CircularInclusionException` to be thrown.

  See Also:
    `CircularInclusionException`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `IncludeReader(java.io.Reader reader)` Constructs an `IncludeReader` with the specified `Reader`.
    `IncludeReader(java.lang.String file)` Constructs an `IncludeReader` with the specified file name.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes all readers associated with this `IncludeReader`.
    `int` | `depth()` Returns the depth of inclusion of the current reader.
    `int` | `getColumnNumber()` Returns the current column number of the current reader.
    `java.lang.String` | `getFile()` Returns the name of the file associated to the current reader - or null if the current reader is not reading from a file.
    `int` | `getLineNumber()` Returns the current line number of the current reader.
    `void` | `include(java.io.Reader reader)` Suspends reading from the current reader and makes further reads proceed with the specified reader.
    `void` | `include(java.lang.String file)` Suspends reading from the current reader and makes further reads proceed with a reader from the specified file.
    `boolean` | `isOutermost()` Returns `true` iff this is reading from the outermost reader.
    `boolean` | `isSeamless()` Returns `true` iff this IncludeReader is seamless.
    `int` | `latestChar()` Returns latest character read in the current reader.
    `void` | `mark(int readAheadLimit)` This method is a simple delegation to the current underlying Reader.
    `boolean` | `markSupported()` This method is a simple delegation to the current underlying Reader.
    `int` | `read()` Reads and returns the next character in this `IncludeReader`.
    `int` | `read(char[] cbuf)` Read characters into an array.
    `int` | `read(char[] cbuf, int off, int len)` Read characters into a portion of an array.
    `boolean` | `ready()` This method is a simple delegation to the current underlying Reader.
    `void` | `reset()` This method is a simple delegation to the current underlying Reader.
    `void` | `setFile(java.lang.String file)` Sets the name of the file associated to the current reader.
    `void` | `setSeamless(boolean flag)` Sets or unsets seamless inclusion mode.
    `long` | `skip(long n)` Skip `n` characters or until IO.EOF is found.
    `java.lang.String` | `toString()` Returns a string form describing the current state of the reader.

    - ### Methods inherited from class java.io.Reader

      `read`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### IncludeReader

          public IncludeReader(java.io.Reader reader)

      Constructs an `IncludeReader` with the specified `Reader`.

    - #### IncludeReader

          public IncludeReader(java.lang.String file)
                        throws java.io.FileNotFoundException

      Constructs an `IncludeReader` with the specified file name.
      Throws:
        `java.io.FileNotFoundException` - (f the specified file does not exist)

  - ### Method Detail

    - #### setSeamless

          public final void setSeamless(boolean flag)

      Sets or unsets seamless inclusion mode.

    - #### isSeamless

          public final boolean isSeamless()

      Returns `true` iff this IncludeReader is seamless.

    - #### getFile

          public final java.lang.String getFile()

      Returns the name of the file associated to the current reader - or null if the current reader is not reading from a file.

    - #### setFile

          public final void setFile(java.lang.String file)

      Sets the name of the file associated to the current reader.

    - #### latestChar

          public final int latestChar()

      Returns latest character read in the current reader.

    - #### getLineNumber

          public final int getLineNumber()

      Returns the current line number of the current reader.

    - #### getColumnNumber

          public final int getColumnNumber()

      Returns the current column number of the current reader.

    - #### close

          public final void close()
                           throws java.io.IOException

      Closes all readers associated with this `IncludeReader`.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in class `java.io.Reader`
      Throws:
        `java.io.IOException` - (if an I/O error occurs)

    - #### depth

          public final int depth()

      Returns the depth of inclusion of the current reader.

    - #### isOutermost

          public final boolean isOutermost()

      Returns `true` iff this is reading from the outermost reader.

    - #### read

          public final int read()
                         throws java.io.IOException

      Reads and returns the next character in this `IncludeReader`. When not in seamless mode, returns `IO.SOI` (resp., `IO.EOI`) right before starting (resp., after ending) reading an inclusion. Returns `IO.EOF` only at the end of the outermost enclosing reader.
      Overrides:
        `read` in class `java.io.Reader`
      Returns:
        The character read (0 to 65535), IO.EOF, IO.EOI, or IO.SOI.
      Throws:
        `java.io.IOException` - (if an I/O error occurs)

    - #### include

          public final void include(java.io.Reader reader)

      Suspends reading from the current reader and makes further reads proceed with the specified reader. Reading from the suspended reader at the exact point it was left resumes automatically upon reaching the end of the included reader.

    - #### include

          public final void include(java.lang.String file)
                             throws java.io.FileNotFoundException,
                                    CircularInclusionException

      Suspends reading from the current reader and makes further reads proceed with a reader from the specified file. Reading from the suspended file reader at the exact point it was left resumes automatically upon reaching the end of the included file.
      Throws:
        `java.io.FileNotFoundException` - (if the specified file does not exist)
        `CircularInclusionException` - (if trying to open an enclosing Reader)

    - #### read

          public int read(char[] cbuf,
                 int off,
                 int len)
                   throws java.io.IOException

      Read characters into a portion of an array. Note that if not in seamless mode, IO.EOI and IO.SOI will be read into the array like any other character.
      Specified by:
        `read` in class `java.io.Reader`
      Parameters:
        `cbuf` - Destination buffer
        `off` - Offset at which to start storing characters
        `len` - Maximum number of characters to read
      Returns:
        number of characters read or IO.EOF
      Throws:
        `java.io.IOException` - (if an I/O error occurs)

    - #### read

          public int read(char[] cbuf)
                   throws java.io.IOException

      Read characters into an array.
      Overrides:
        `read` in class `java.io.Reader`
      Parameters:
        `cbuf` - Destination buffer
      Returns:
        Number of characters read, or one of IO.EOF, IO.SOI, or IO.EOI.
      Throws:
        `java.io.IOException` - (if an I/O error occurs)

    - #### skip

          public final long skip(long n)
                          throws java.io.IOException

      Skip `n` characters or until IO.EOF is found. Note that IO.SOI and IO.EOI are skipped but not counted, regardless of whether the inclusion mode is seamless or not.
      Overrides:
        `skip` in class `java.io.Reader`
      Parameters:
        `n` - The number of characters to skip
      Returns:
        The number of characters actually skipped
      Throws:
        `java.lang.IllegalArgumentException` - (if n is negative)
        `java.io.IOException` - (if an I/O error occurs)

    - #### ready

          public boolean ready()
                        throws java.io.IOException

      This method is a simple delegation to the current underlying Reader. Note that this way of handling it does not take into account other Readers being suspended in the Reader stack. What is returned depends only on the current underlying Reader.
      Overrides:
        `ready` in class `java.io.Reader`
      Throws:
        `java.io.IOException`

    - #### markSupported

          public boolean markSupported()

      This method is a simple delegation to the current underlying Reader. Note that this way of handling it does not take into account other Readers being suspended in the Reader stack. What is returned depends only on the current underlying Reader.
      Overrides:
        `markSupported` in class `java.io.Reader`

    - #### mark

          public void mark(int readAheadLimit)
                    throws java.io.IOException

      This method is a simple delegation to the current underlying Reader. Note that this way of handling it does not take into account other Readers being suspended in the Reader stack. In particular, preserving the mark cannot be done past the end of the current underlying Reader.
      Overrides:
        `mark` in class `java.io.Reader`
      Throws:
        `java.io.IOException`

    - #### reset

          public void reset()
                     throws java.io.IOException

      This method is a simple delegation to the current underlying Reader. Note that this way of handling it does not take into account other Readers being suspended in the Reader stack. In particular, it will not reset past the beginning of the current Reader.
      Overrides:
        `reset` in class `java.io.Reader`
      Throws:
        `java.io.IOException`

    - #### toString

          public final java.lang.String toString()

      Returns a string form describing the current state of the reader.
      Overrides:
        `toString` in class `java.lang.Object`