Class EscapedLineReader
- java.lang.Object
-
- java.io.Reader
-
- java.io.BufferedReader
-
- java.io.LineNumberReader
-
- ca.cgjennings.io.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 byr
(carriage return),n
(newline),s
(space),\
(a backslash),#
(hash),!
(bang), oruxxxx
(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
-
-
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, ornull
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.
-
-
-
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 streambufferSize
- 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 fromcharset
- 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 fromcharset
- 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 fromcharset
- 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 fromcharset
- 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 classjava.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 forreadProperty( 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 withreadLine()
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
- iftrue
, 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, ornull
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 returnsnull
.- 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, seereadLineUnescaped()
.- Parameters:
line
- the line to unescape- Returns:
- the unescaped line
-
-