Package ca.cgjennings.io

Class EscapedLineReader

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.lang.Readable
    public class EscapedLineReader
extends java.io.LineNumberReader
    A buffered input stream reader that transparently converts escaped characters into their original form. The escape sequences it recognizes are based on those used in .properties files. All escape sequences begin with a backslash (\). This can be followed by r (carriage return), n (newline), s (space), \ (a backslash), # (hash), ! (bang), or uxxxx (to encode any Unicode character; xxxx are the 4 hex digits of a UTF-16 character).

    Lines are trimmed of leading and trailing whitespace before being returned. (Use escape characters to prevent this trimming.) A trimmed line that starts with an unescaped # or ! character will be treated as a comment. The reader will silently skip these lines.

    If a line ends with a backslash, the following line will automatically be merged with this line. For example, the following would be read in as a single line: 

     Pease porridge hot, pease porridge cold, \
 Pease porridge in the pot, nine days old; \
 Some like it hot, some like it cold, \
 Some like it in the pot, nine days old.

    The reader tracks the line number of each line as it is read in, for use in reporting errors. Line numbering starts at 1.

    Author:
    Chris Jennings

    • Field Summary

      • Fields inherited from class java.io.Reader

        lock

    • Constructor Summary

      Constructors 
      Constructor Description
      EscapedLineReader​(java.io.File f)
      Creates a line reader that reads from the specified file, using a default buffer size and the ISO-8859-15 encoding.
      EscapedLineReader​(java.io.File f, java.lang.String charset)
      Creates a line reader that reads from the specified file, using a default buffer size and the specified encoding.
      EscapedLineReader​(java.io.InputStream in)
      Creates a line reader for the specified input stream using a default buffer size.
      EscapedLineReader​(java.io.InputStream in, java.lang.String charset)
      Creates a line reader for the specified input stream using a default buffer size and the specified character set encoding.
      EscapedLineReader​(java.io.InputStream in, java.nio.charset.Charset charset)
      Creates a line reader for the specified input stream using a default buffer size and the specified character set encoding.
      EscapedLineReader​(java.io.Reader in)
      Creates a line reader using the specified reader and a default buffer size.
      EscapedLineReader​(java.io.Reader in, int bufferSize)
      Creates a line reader using the specified reader and buffer size.
      EscapedLineReader​(java.net.URL url)
      Creates a line reader that reads from the specified URL, using a default buffer size and the ISO-8859-15 encoding.
      EscapedLineReader​(java.net.URL url, java.lang.String charset)
      Creates a line reader for the specified URL using a default buffer size and the specified character set encoding.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getFirstCommentBlock()
      If the reader has read past the first contiguous block of comment lines in the stream, this method returns that comment block.
      java.lang.String readLine()
      Returns the next logical line from the stream, or null if the end of the stream has been reached.The next logical line may consist of several "natural" lines in the original file.Natural lines are concatenated into a single logical line when a backslash character occurs immediately before the line separator between them.
      java.lang.String readNonemptyLine()
      Return the next line which is not a comment and which contains non-whitespace characters, or null if the end of the stream is reached.
      java.util.Map<java.lang.String,​java.lang.String> readProperties​(java.util.Map<java.lang.String,​java.lang.String> props)
      Reads all remaining lines as a series of [key, value] pairs and stores them in the specified map.
      java.lang.String[] readProperty()
      Reads a [key,value] pair, skipping empty lines.
      java.lang.String[] readProperty​(boolean skipEmptyLines)
      Reads a [key,value] pair.
      static java.lang.String unescapeLine​(java.lang.String line)
      Remove escape sequences from a line, if any.

      • Methods inherited from class java.io.LineNumberReader

        getLineNumber, mark, read, read, reset, setLineNumber, skip

      • Methods inherited from class java.io.BufferedReader

        close, lines, markSupported, ready

      • Methods inherited from class java.io.Reader

        nullReader, read, read, transferTo

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • EscapedLineReader

        public EscapedLineReader​(java.io.Reader in)
        Creates a line reader using the specified reader and a default buffer size.
        Parameters:
        in - a reader that will provide the raw character stream

      • EscapedLineReader

        public EscapedLineReader​(java.io.Reader in,
                         int bufferSize)
        Creates a line reader using the specified reader and buffer size.
        Parameters:
        in - a reader that will provide the raw character stream
        bufferSize - the size of the input buffer

      • EscapedLineReader

        public EscapedLineReader​(java.io.InputStream in)
        Creates a line reader for the specified input stream using a default buffer size. The encoding is assumed to be ISO-8859-15.
        Parameters:
        in - the input stream to read from

      • EscapedLineReader

        public EscapedLineReader​(java.io.InputStream in,
                         java.lang.String charset)
                  throws java.io.UnsupportedEncodingException
        Creates a line reader for the specified input stream using a default buffer size and the specified character set encoding.
        Parameters:
        in - the input stream to read from
        charset - the name of the character set to use, such as "UTF-8"
        Throws:
        java.io.UnsupportedEncodingException

      • EscapedLineReader

        public EscapedLineReader​(java.io.InputStream in,
                         java.nio.charset.Charset charset)
        Creates a line reader for the specified input stream using a default buffer size and the specified character set encoding.
        Parameters:
        in - the input stream to read from
        charset - the character set to use

      • EscapedLineReader

        public EscapedLineReader​(java.net.URL url)
                  throws java.io.IOException
        Creates a line reader that reads from the specified URL, using a default buffer size and the ISO-8859-15 encoding.
        Parameters:
        url - the URL to read from
        Throws:
        java.io.IOException

      • EscapedLineReader

        public EscapedLineReader​(java.net.URL url,
                         java.lang.String charset)
                  throws java.io.IOException
        Creates a line reader for the specified URL using a default buffer size and the specified character set encoding.
        Parameters:
        url - the URL to read from
        charset - the name of the character set to use, such as "UTF-8"
        Throws:
        java.io.IOException

      • EscapedLineReader

        public EscapedLineReader​(java.io.File f)
                  throws java.io.IOException
        Creates a line reader that reads from the specified file, using a default buffer size and the ISO-8859-15 encoding.
        Parameters:
        f - the file to read from
        Throws:
        java.io.IOException

      • EscapedLineReader

        public EscapedLineReader​(java.io.File f,
                         java.lang.String charset)
                  throws java.io.IOException
        Creates a line reader that reads from the specified file, using a default buffer size and the specified encoding.
        Parameters:
        f - the file to read from
        charset - the name of the character set to use, such as "UTF-8"
        Throws:
        java.io.IOException

    • Method Detail

      • readLine

        public java.lang.String readLine()
                          throws java.io.IOException
        Returns the next logical line from the stream, or null if the end of the stream has been reached.The next logical line may consist of several "natural" lines in the original file.Natural lines are concatenated into a single logical line when a backslash character occurs immediately before the line separator between them. For example: 
         These two natural lines will \
 form a single logical line.

        A backslash is also used to introduce escape sequences. The sequences \n, \r, \t, and \f are replaced by a newline, return, tab, or formfeed character, respectively. The sequence (where 0000 is a sequence of four hexadecimal digits) is replaced by the 16-bit Unicode character with the specified value. A backslash followed by any other character (including another backslash) is replaced by the following character, effectively deleting the initial backslash.

        Lines whose first non-whitespace character is '#' or '!' are considered comments and will be skipped. If a line continuation backslash occurs before a comment line, the first non-comment line that follows will be concatenated to the continued line. If a line continuation backslash occurs on a comment line, it is ignored. To include a comment character as the first character of a non-comment line, escape it with a backslash.

        Overrides:
        readLine in class java.io.LineNumberReader
        Returns:
        the next converted line
        Throws:
        java.io.IOException

      • readProperty

        public java.lang.String[] readProperty()
                                throws java.io.IOException
        Reads a [key,value] pair, skipping empty lines. This is a cover for readProperty( true ).
        Returns:
        a key, value pair or null
        Throws:
        java.io.IOException

      • readProperty

        public java.lang.String[] readProperty​(boolean skipEmptyLines)
                                throws java.io.IOException
        Reads a [key,value] pair. This is done by reading a line as with readLine() and then splitting the line into a key and value. Splitting is performed by locating the first unescaped equals sign; text prior to this point becomes the key while text after this point becomes the value. The key and value are both trimmed before being returned. If the line does not have an unescaped equals sign, then the entire line is treated as the key and the value will be an empty string.
        Parameters:
        skipEmptyLines - if true, any empty lines will be silently skipped
        Returns:
        a key, value pair or null
        Throws:
        java.io.IOException

      • readProperties

        public java.util.Map<java.lang.String,​java.lang.String> readProperties​(java.util.Map<java.lang.String,​java.lang.String> props)
                                                                      throws java.io.IOException
        Reads all remaining lines as a series of [key, value] pairs and stores them in the specified map.
        Parameters:
        props - the non-null map to add the read properties to
        Throws:
        java.io.IOException - if an I/O error occurs

      • readNonemptyLine

        public java.lang.String readNonemptyLine()
                                  throws java.io.IOException
        Return the next line which is not a comment and which contains non-whitespace characters, or null if the end of the stream is reached.
        Returns:
        the next non-comment, non-empty line, or null
        Throws:
        java.io.IOException

      • getFirstCommentBlock

        public java.lang.String getFirstCommentBlock()
        If the reader has read past the first contiguous block of comment lines in the stream, this method returns that comment block. Otherwise, it returns null.
        Returns:
        the first comment block in the file, if it has been read

      • unescapeLine

        public static java.lang.String unescapeLine​(java.lang.String line)
        Remove escape sequences from a line, if any. Returns null if the given line is null. For a list of sequences and their effects, see readLineUnescaped().
        Parameters:
        line - the line to unescape
        Returns:
        the unescaped line