IncludeReader (API documentation of hlt.language packages)

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 IncludeReaders 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

Class IncludeReader

Constructor Summary

Method Summary

Methods inherited from class java.io.Reader

Methods inherited from class java.lang.Object

Constructor Detail

IncludeReader

IncludeReader

Method Detail

setSeamless

isSeamless

getFile

setFile

latestChar

getLineNumber

getColumnNumber

close

depth

isOutermost

read

include

include

read

read

skip

ready

markSupported

mark

reset

toString