public class LineAppender extends Object implements Flushable
Appendable
which can apply different kinds of reformatting that depend on the
End Of Line (EOL) occurrences. Available reformatting include inserting a
a margin before each line, wrapping to a maximal line length and replacing tabulations or
EOL characters. The actual work to be done can be enabled by invoking one or many of the
following methods:
setMaximalLineLength(int)
for wrapping the lines to some maximal line length,
typically 80 Unicode characters (code points).setTabulationExpanded(boolean)
for replacing tabulation characters by spaces.setLineSeparator(String)
for replacing all occurrences of
line separators by the given string.char
primitive values, but not always. Combining characters are not
yet recognized by this class, but future versions may improve on that.
For proper line length calculation in presence of tabulation characters ('\t'
),
this class needs to known the tabulation width. The default value is 8, but this can be changed
by a call to setTabulationWidth(int)
. Note that invoking that method affects only line
length calculation; it does not replace tabulations by spaces. For tabulation expansion, see
setTabulationExpanded(boolean)
.
Defined in the sis-utility
module
Modifier and Type | Field and Description |
---|---|
protected Appendable |
out
The underlying character output stream or buffer.
|
Constructor and Description |
---|
LineAppender(Appendable out)
Constructs a default formatter.
|
LineAppender(Appendable out,
int maximalLineLength,
boolean isTabulationExpanded)
Constructs a formatter which will wrap the lines at a given maximal length.
|
LineAppender(Appendable out,
String lineSeparator,
boolean isTabulationExpanded)
Constructs a formatter which will replaces line separators by the given string.
|
Modifier and Type | Method and Description |
---|---|
Appendable |
append(char c)
Writes a single character.
|
Appendable |
append(CharSequence sequence)
Appends the specified character sequence.
|
Appendable |
append(CharSequence sequence,
int start,
int end)
Writes a portion of a character sequence.
|
void |
clear()
Resets the
LineAppender internal state as if a new line was beginning. |
void |
flush()
Sends all pending characters to the underlying appendable, including trailing whitespaces.
|
String |
getLineSeparator()
Returns the line separator to be sent to the underlying appendable,
or
null if EOL sequences are forwarded unchanged. |
int |
getMaximalLineLength()
Returns the maximal line length, in unit of Unicode characters (code point count).
|
int |
getTabulationWidth()
Returns the current tabulation width, in unit of Unicode characters (code point count).
|
boolean |
isTabulationExpanded()
Returns
true if this formatter expands tabulations into spaces. |
protected void |
onLineBegin(boolean isContinuation)
Invoked when a new line is beginning.
|
void |
setLineSeparator(String lineSeparator)
Changes the line separator to be sent to the underlying appendable.
|
void |
setMaximalLineLength(int length)
Sets the maximal line length, in units of Unicode characters (code point count).
|
void |
setTabulationExpanded(boolean expanded)
Sets whether this class formatter expands tabulations into spaces.
|
void |
setTabulationWidth(int width)
Sets the tabulation width, in unit of Unicode characters (code point count).
|
String |
toString()
Returns the content of this
Appendable as a string if possible,
or the localized "Unavailable content" string otherwise. |
protected final Appendable out
public LineAppender(Appendable out)
out
- the underlying stream or buffer to write to.public LineAppender(Appendable out, String lineSeparator, boolean isTabulationExpanded)
out
- the underlying stream or buffer to write to.lineSeparator
- the line separator to send to out
, or null
for forwarding the EOL sequences unchanged.isTabulationExpanded
- true
for expanding tabulations into spaces,
or false
for sending '\t'
characters as-is.public LineAppender(Appendable out, int maximalLineLength, boolean isTabulationExpanded)
out
- the underlying stream or buffer to write to.maximalLineLength
- the maximal number of Unicode characters per line,
or Integer.MAX_VALUE
if there is no limit.isTabulationExpanded
- true
for expanding tabulations into spaces,
or false
for forwarding '\t'
characters as-is.public int getMaximalLineLength()
Integer.MAX_VALUE
if there is no limit.public void setMaximalLineLength(int length)
length
- the new maximal number of Unicode characters per line,
or Integer.MAX_VALUE
if there is no limit.public int getTabulationWidth()
public void setTabulationWidth(int width)
width
- the new tabulation width. Must be greater than 0.IllegalArgumentException
- if tabWidth
is not greater than 0
or is unreasonably high.public boolean isTabulationExpanded()
true
if this formatter expands tabulations into spaces.
The default value is false
, which means that '\t'
characters
are sent to the underlying appendable as-is.true
if this formatter expands tabulations into spaces,
or false
if '\t'
characters are forwarded as-is.public void setTabulationExpanded(boolean expanded)
expanded
- true
if this class shall expands tabulations into spaces,
or false
for forwarding '\t'
characters as-is.public String getLineSeparator()
null
if EOL sequences are forwarded unchanged.null
if EOL are forwarded as-is.public void setLineSeparator(String lineSeparator)
"\r"
, "\n"
,
"\r\n"
or other line separators.
If null
(the default), then the line separators given to the append
methods are forwarded unchanged.lineSeparator
- the new line separator, or null
for forwarding EOL as-is.Characters.isLineOrParagraphSeparator(int)
public Appendable append(char c) throws IOException
append
in interface Appendable
c
- the character to append.Appendable
.IOException
- if an I/O error occurs.public Appendable append(CharSequence sequence, int start, int end) throws IOException
append
in interface Appendable
sequence
- the character sequence to be written.start
- index from which to start reading characters.end
- index of the character following the last character to read.Appendable
.IOException
- if an I/O error occurs.public void clear() throws IOException
LineAppender
internal state as if a new line was beginning.
Trailing whitespaces not yet sent to the underlying appendable
are discarded, and the column position (for tabulation expansion calculation) is
reset to 0. This method does not write any line separator.IOException
- if an error occurred while sending the trailing non-white
characters to the underlying stream.public void flush() throws IOException
LineAppender
to properly wrap the current
line if the current position is in the middle of a word.
Invoking this method also flushes the underlying stream, if flushable.
A cheaper way to send pending characters is to make sure that the last character is a
line or paragraph terminator,
or to invoke clear()
.
flush
in interface Flushable
IOException
- if an I/O error occurs.protected void onLineBegin(boolean isContinuation) throws IOException
If an implementation wishes to write characters, it shall do so by writing
directly to out
, not by invoking the append
methods of this class.
isContinuation
- true
if the new line is the continuation of the previous
line after a "line wrap", or false
if a line or paragraph separator has
been explicitly sent to this formatter.IOException
- if an error occurred while writing to out
.public Appendable append(CharSequence sequence) throws IOException
Appendable.append(CharSequence, int, int)
.append
in interface Appendable
sequence
- the character sequence to append, or null
.Appendable
.IOException
- if an I/O error occurred.public String toString()
Appendable
as a string if possible,
or the localized "Unavailable content" string otherwise.toString
in class Object
Appendable
, or a localized message for unavailable content.IO.content(Appendable)
Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.