Class LineAppender
- All Implemented Interfaces:
Flushable
,Appendable
- Direct Known Subclasses:
PropertyFormat
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.
How line lengths are calculated
Line length are measured in unit of Unicode code points. This is usually the same than the number ofchar
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)
.
- Since:
- 0.3
- Version:
- 0.4
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final StringBuilder
The buffer for the last word being written.private int
The length of the current line, in units of code points (notchar
).private boolean
true
if all occurrences of EOL sequences shall be replaced by thelineSeparator
, orfalse
for keeping EOL unchanged.private boolean
true
if an escape sequence is in progress.private boolean
true
if the next character will be at the beginning of a new line.private boolean
true
if this formatter shall expands tabulations into spaces.private String
The line separator, ornull
if not yet determined.private int
The maximal line length, in units of code points (notchar
).private int
The number of Java characters (not Unicode code points) inbuffer
, ignoring trailing whitespaces.private boolean
true
if the next character needs to be skipped if equals to'\n'
.private short
The tabulation width, in number of code points. -
Constructor Summary
ConstructorsConstructorDescriptionLineAppender
(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. -
Method Summary
Modifier and TypeMethodDescriptionappend
(char c) Writes a single character.append
(CharSequence sequence, int start, int end) Writes a portion of a character sequence.void
clear()
Resets theLineAppender
internal state as if a new line was beginning.private void
deleteSoftHyphen
(int i) Removes the soft hyphen characters from the given buffer.private void
Writes pending non-white characters, discards trailing whitespaces, and resets column position to zero.void
flush()
Sends all pending characters to the underlying appendable, including trailing whitespaces.Returns the line separator to be sent to the underlying appendable, ornull
if EOL sequences are forwarded unchanged.int
Returns the maximal line length, in unit of Unicode characters (code point count).int
Returns the current tabulation width, in unit of Unicode characters (code point count).boolean
Returnstrue
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).private void
transfer
(int length) Writes the given amount of characters from the buffer, then removes those characters from the buffer.private void
write
(int c) Writes the specified code point.private void
Writes a line separator toAppender.out
.Methods inherited from class org.apache.sis.io.Appender
append, appendCodePoint, appendSurrogate, isHighSurrogate, lineSeparator, toCodePoint, toString
-
Field Details
-
lineSeparator
The line separator, ornull
if not yet determined. Ifnull
, then theappend(CharSequence, int, int)
method will try to infer it from the submitted text.If
isEndOfLineReplaced
isfalse
(the default), then this line separator will be used only when this class inserts new line separators as a consequence of line wraps; line separators found in the texts given by the user will be passed "as is". Iftrue
, then all line separators are replaced. -
maximalLineLength
private int maximalLineLengthThe maximal line length, in units of code points (notchar
). Can be set toInteger.MAX_VALUE
if there is no limit.- See Also:
-
codePointCount
private int codePointCountThe length of the current line, in units of code points (notchar
). It may be greater than the length ofbuffer
because the latter contains only the last word. -
tabulationWidth
private short tabulationWidthThe tabulation width, in number of code points.- See Also:
-
isTabulationExpanded
private boolean isTabulationExpandedtrue
if this formatter shall expands tabulations into spaces.- See Also:
-
isEndOfLineReplaced
private boolean isEndOfLineReplacedtrue
if all occurrences of EOL sequences shall be replaced by thelineSeparator
, orfalse
for keeping EOL unchanged. -
skipLF
private boolean skipLFtrue
if the next character needs to be skipped if equals to'\n'
. This field is used in order to avoid writing two EOL in place of"\r\n"
. -
isNewLine
private boolean isNewLinetrue
if the next character will be at the beginning of a new line. This flag is set totrue
only for "real" new lines, as a result of line separator found in the input given to this formatter. The "generated" new lines (resulting from line wrap) will invokeonLineBegin(boolean)
directly without the help of this temporary variable.- See Also:
-
isEscapeSequence
private boolean isEscapeSequencetrue
if an escape sequence is in progress. The escape sequence will stop after the first non-digit character other thanX364.BRACKET
. -
buffer
The buffer for the last word being written. This buffer will also contain trailing whitespace characters. If whitespaces are followed by at least one non-white character, then the whitespaces are written to the underlying stream before the non-ignorable one. Otherwise if whitespaces are followed by a line separator, then they are discarded. -
printableLength
private int printableLengthThe number of Java characters (not Unicode code points) inbuffer
, ignoring trailing whitespaces.
-
-
Constructor Details
-
LineAppender
Constructs a default formatter. Callers should invoke at least one of the following methods after construction in order to perform useful work:- Parameters:
out
- the underlying stream or buffer to write to.
-
LineAppender
Constructs a formatter which will replaces line separators by the given string.- Parameters:
out
- the underlying stream or buffer to write to.lineSeparator
- the line separator to send toout
, ornull
for forwarding the EOL sequences unchanged.isTabulationExpanded
-true
for expanding tabulations into spaces, orfalse
for sending'\t'
characters as-is.
-
LineAppender
Constructs a formatter which will wrap the lines at a given maximal length.- Parameters:
out
- the underlying stream or buffer to write to.maximalLineLength
- the maximal number of Unicode characters per line, orInteger.MAX_VALUE
if there is no limit.isTabulationExpanded
-true
for expanding tabulations into spaces, orfalse
for forwarding'\t'
characters as-is.
-
-
Method Details
-
getMaximalLineLength
public int getMaximalLineLength()Returns the maximal line length, in unit of Unicode characters (code point count). The default value is no limit.- Returns:
- the current maximal number of Unicode characters per line,
or
Integer.MAX_VALUE
if there is no limit.
-
setMaximalLineLength
public void setMaximalLineLength(int length) Sets the maximal line length, in units of Unicode characters (code point count).- Parameters:
length
- the new maximal number of Unicode characters per line, orInteger.MAX_VALUE
if there is no limit.
-
getTabulationWidth
public int getTabulationWidth()Returns the current tabulation width, in unit of Unicode characters (code point count). The default value is 8.- Returns:
- the current tabulation width in number of Unicode characters.
-
setTabulationWidth
public void setTabulationWidth(int width) Sets the tabulation width, in unit of Unicode characters (code point count).- Parameters:
width
- the new tabulation width. Must be greater than 0.- Throws:
IllegalArgumentException
- iftabWidth
is not greater than 0 or is unreasonably high.
-
isTabulationExpanded
public boolean isTabulationExpanded()Returnstrue
if this formatter expands tabulations into spaces. The default value isfalse
, which means that'\t'
characters are sent to the underlying appendable as-is.- Returns:
true
if this formatter expands tabulations into spaces, orfalse
if'\t'
characters are forwarded as-is.
-
setTabulationExpanded
public void setTabulationExpanded(boolean expanded) Sets whether this class formatter expands tabulations into spaces.- Parameters:
expanded
-true
if this class shall expands tabulations into spaces, orfalse
for forwarding'\t'
characters as-is.
-
getLineSeparator
Returns the line separator to be sent to the underlying appendable, ornull
if EOL sequences are forwarded unchanged.- Returns:
- the current line separator, or
null
if EOL are forwarded as-is.
-
setLineSeparator
Changes the line separator to be sent to the underlying appendable. This is the string to insert in place of every occurrences of"\r"
,"\n"
,"\r\n"
or other line separators. Ifnull
(the default), then the line separators given to theappend
methods are forwarded unchanged.- Parameters:
lineSeparator
- the new line separator, ornull
for forwarding EOL as-is.- See Also:
-
writeLineSeparator
Writes a line separator toAppender.out
. This method is invoked for new line separators generated by this class, not for the line separators found in the texts supplied by the user, unlessisEndOfLineReplaced
istrue
. Theappend(CharSequence,int,int)
method tries to detect the line separator used in the text, but if no line separator has been found we have to use some fallback.- Throws:
IOException
-
endOfLine
Writes pending non-white characters, discards trailing whitespaces, and resets column position to zero. This method does not write the line separator and does not modify the status of theskipLF
flag; those tasks are caller's responsibility.- Throws:
IOException
-
deleteSoftHyphen
private void deleteSoftHyphen(int i) Removes the soft hyphen characters from the given buffer. This is invoked when the buffer is about to be written without being split on two lines.- Parameters:
i
- index after the last character to check. This is eitherprintableLength
for checking all characters, orprintableLength-1
for preserving the last soft hyphen on the line (while removing all others).
-
transfer
Writes the given amount of characters from the buffer, then removes those characters from the buffer. This method does not adjustprintableLength
; it is caller responsibility to do so.- Throws:
IOException
-
write
Writes the specified code point.- Throws:
IOException
- if an I/O error occurs.
-
append
Writes a single character.- Specified by:
append
in interfaceAppendable
- Parameters:
c
- the character to append.- Returns:
- a reference to this
Appendable
. - Throws:
IOException
- if an I/O error occurs.
-
append
Writes a portion of a character sequence.- Specified by:
append
in interfaceAppendable
- Parameters:
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.- Returns:
- a reference to this
Appendable
. - Throws:
IOException
- if an I/O error occurs.
-
clear
Resets theLineAppender
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.- Throws:
IOException
- if an error occurred while sending the trailing non-white characters to the underlying stream.
-
flush
Sends all pending characters to the underlying appendable, including trailing whitespaces. Note that this method should preferably be invoked at the end of a word, sentence or line, since invoking this method may preventLineAppender
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()
.- Specified by:
flush
in interfaceFlushable
- Throws:
IOException
- if an I/O error occurs.
-
onLineBegin
Invoked when a new line is beginning. The default implementation does nothing, but subclasses can override this method for example in order to insert a margin on the left side before each line.If an implementation wishes to write characters, it shall do so by writing directly to
Appender.out
, not by invoking theappend
methods of this class.- Parameters:
isContinuation
-true
if the new line is the continuation of the previous line after a "line wrap", orfalse
if a line or paragraph separator has been explicitly sent to this formatter.- Throws:
IOException
- if an error occurred while writing toAppender.out
.
-