Class LineAppender
- All Implemented Interfaces:
Flushable,Appendable
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
Defined in the sis-utility module
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final AppendableThe underlying character output stream or buffer. -
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) Appends the specified character sequence.append(CharSequence sequence, int start, int end) Writes a portion of a character sequence.voidclear()Resets theLineAppenderinternal state as if a new line was beginning.voidflush()Sends all pending characters to the underlying appendable, including trailing whitespaces.Returns the line separator to be sent to the underlying appendable, ornullif EOL sequences are forwarded unchanged.intReturns the maximal line length, in unit of Unicode characters (code point count).intReturns the current tabulation width, in unit of Unicode characters (code point count).booleanReturnstrueif this formatter expands tabulations into spaces.protected voidonLineBegin(boolean isContinuation) Invoked when a new line is beginning.voidsetLineSeparator(String lineSeparator) Changes the line separator to be sent to the underlying appendable.voidsetMaximalLineLength(int length) Sets the maximal line length, in units of Unicode characters (code point count).voidsetTabulationExpanded(boolean expanded) Sets whether this class formatter expands tabulations into spaces.voidsetTabulationWidth(int width) Sets the tabulation width, in unit of Unicode characters (code point count).Returns the content of thisAppendableas a string if possible, or the localized "Unavailable content" string otherwise.
-
Field Details
-
out
The underlying character output stream or buffer.
-
-
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, ornullfor forwarding the EOL sequences unchanged.isTabulationExpanded-truefor expanding tabulations into spaces, orfalsefor 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_VALUEif there is no limit.isTabulationExpanded-truefor expanding tabulations into spaces, orfalsefor 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_VALUEif 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_VALUEif 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- iftabWidthis not greater than 0 or is unreasonably high.
-
isTabulationExpanded
public boolean isTabulationExpanded()Returnstrueif this formatter expands tabulations into spaces. The default value isfalse, which means that'\t'characters are sent to the underlying appendable as-is.- Returns:
trueif this formatter expands tabulations into spaces, orfalseif'\t'characters are forwarded as-is.
-
setTabulationExpanded
public void setTabulationExpanded(boolean expanded) Sets whether this class formatter expands tabulations into spaces.- Parameters:
expanded-trueif this class shall expands tabulations into spaces, orfalsefor forwarding'\t'characters as-is.
-
getLineSeparator
Returns the line separator to be sent to the underlying appendable, ornullif EOL sequences are forwarded unchanged.- Returns:
- the current line separator, or
nullif 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 theappendmethods are forwarded unchanged.- Parameters:
lineSeparator- the new line separator, ornullfor forwarding EOL as-is.- See Also:
-
append
Writes a single character.- Specified by:
appendin 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:
appendin 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 theLineAppenderinternal 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 preventLineAppenderto 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:
flushin 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
out, not by invoking theappendmethods of this class.- Parameters:
isContinuation-trueif the new line is the continuation of the previous line after a "line wrap", orfalseif a line or paragraph separator has been explicitly sent to this formatter.- Throws:
IOException- if an error occurred while writing toout.
-
append
Appends the specified character sequence. The default implementation delegates toAppendable.append(CharSequence, int, int).- Specified by:
appendin interfaceAppendable- Parameters:
sequence- the character sequence to append, ornull.- Returns:
- a reference to this
Appendable. - Throws:
IOException- if an I/O error occurred.
-
toString
Returns the content of thisAppendableas a string if possible, or the localized "Unavailable content" string otherwise.
-