Module org.apache.sis.util
Package org.apache.sis.io

Class LineAppender

Object
LineAppender
All Implemented Interfaces:
Flushable, Appendable
public class LineAppender extends Object implements Flushable
An 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: In addition this class removes trailing whitespaces before end of lines.

How line lengths are calculated

Line length are measured in unit of Unicode code points. This is usually the same than the number of 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 set­Tabulation­Width(int). Note that invoking that method affects only line length calculation; it does not replace tabulations by spaces. For tabulation expansion, see set­Tabulation­Expanded(boolean).

Since:
0.3

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final Appendable
    out
    The underlying character output stream or buffer.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Line­Appender(Appendable out)
    Constructs a default formatter.
    Line­Appender(Appendable out, int maximal­Line­Length, boolean is­Tabulation­Expanded)
    Constructs a formatter which will wrap the lines at a given maximal length.
    Line­Appender(Appendable out, String line­Separator, boolean is­Tabulation­Expanded)
    Constructs a formatter which will replaces line separators by the given string.

  • Method Summary

    Modifier and Type
    Method
    Description
    Appendable
    append(char c)
    Writes a single character.
    Appendable
    append(Char­Sequence sequence)
    Appends the specified character sequence.
    Appendable
    append(Char­Sequence sequence, int start, int end)
    Writes a portion of a character sequence.
    void
    clear()
    Resets the Line­Appender internal state as if a new line was beginning.
    void
    flush()
    Sends all pending characters to the underlying appendable, including trailing whitespaces.
    String
    get­Line­Separator()
    Returns the line separator to be sent to the underlying appendable, or null if EOL sequences are forwarded unchanged.
    int
    get­Maximal­Line­Length()
    Returns the maximal line length, in unit of Unicode characters (code point count).
    int
    get­Tabulation­Width()
    Returns the current tabulation width, in unit of Unicode characters (code point count).
    boolean
    is­Tabulation­Expanded()
    Returns true if this formatter expands tabulations into spaces.
    protected void
    on­Line­Begin(boolean is­Continuation)
    Invoked when a new line is beginning.
    void
    set­Line­Separator(String line­Separator)
    Changes the line separator to be sent to the underlying appendable.
    void
    set­Maximal­Line­Length(int length)
    Sets the maximal line length, in units of Unicode characters (code point count).
    void
    set­Tabulation­Expanded(boolean expanded)
    Sets whether this class formatter expands tabulations into spaces.
    void
    set­Tabulation­Width(int width)
    Sets the tabulation width, in unit of Unicode characters (code point count).
    String
    to­String()
    Returns the content of this Appendable as a string if possible, or the localized "Unavailable content" string otherwise.

    Methods inherited from class Object

    clone, equals, finalize, get­Class, hash­Code, notify, notify­All, wait, wait, wait

  • Field Details

    • out

      protected final Appendable out
      The underlying character output stream or buffer.

  • Constructor Details

    • LineAppender

      public LineAppender(Appendable out)
      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

      public LineAppender(Appendable out, String lineSeparator, boolean isTabulationExpanded)
      Constructs a formatter which will replaces line separators by the given string.
      Parameters:
      out - the underlying stream or buffer to write to.
      line­Separator - the line separator to send to out, or null for forwarding the EOL sequences unchanged.
      is­Tabulation­Expanded - true for expanding tabulations into spaces, or false for sending '\t' characters as-is.

    • LineAppender

      public LineAppender(Appendable out, int maximalLineLength, boolean isTabulationExpanded)
      Constructs a formatter which will wrap the lines at a given maximal length.
      Parameters:
      out - the underlying stream or buffer to write to.
      maximal­Line­Length - the maximal number of Unicode characters per line, or Integer​.MAX_VALUE if there is no limit.
      is­Tabulation­Expanded - true for expanding tabulations into spaces, or false 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, or Integer​.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:
      Illegal­Argument­Exception - if tab­Width is not greater than 0 or is unreasonably high.

    • isTabulationExpanded

      public boolean isTabulationExpanded()
      Returns 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.
      Returns:
      true if this formatter expands tabulations into spaces, or false 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, or false for forwarding '\t' characters as-is.

    • getLineSeparator

      public String getLineSeparator()
      Returns the line separator to be sent to the underlying appendable, or null if EOL sequences are forwarded unchanged.
      Returns:
      the current line separator, or null if EOL are forwarded as-is.

    • setLineSeparator

      public void setLineSeparator(String lineSeparator)
      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. If null (the default), then the line separators given to the append methods are forwarded unchanged.
      Parameters:
      line­Separator - the new line separator, or null for forwarding EOL as-is.
      See Also:

    • append

      public Appendable append(char c) throws IOException
      Writes a single character.
      Specified by:
      append in interface Appendable
      Parameters:
      c - the character to append.
      Returns:
      a reference to this Appendable.
      Throws:
      IOException - if an I/O error occurs.

    • append

      public Appendable append(CharSequence sequence, int start, int end) throws IOException
      Writes a portion of a character sequence.
      Specified by:
      append in interface Appendable
      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

      public void clear() throws IOException
      Resets the Line­Appender 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

      public void flush() throws IOException
      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 prevent Line­Appender 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 interface Flushable
      Throws:
      IOException - if an I/O error occurs.

    • onLineBegin

      protected void onLineBegin(boolean isContinuation) throws IOException
      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 the append methods of this class.

      Parameters:
      is­Continuation - 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.
      Throws:
      IOException - if an error occurred while writing to out.

    • append

      public Appendable append(CharSequence sequence) throws IOException
      Appends the specified character sequence. The default implementation delegates to Appendable​.append(Char­Sequence, int, int).
      Specified by:
      append in interface Appendable
      Parameters:
      sequence - the character sequence to append, or null.
      Returns:
      a reference to this Appendable.
      Throws:
      IOException - if an I/O error occurred.

    • toString

      public String toString()
      Returns the content of this Appendable as a string if possible, or the localized "Unavailable content" string otherwise.
      Overrides:
      to­String in class Object
      Returns:
      the content of this Appendable, or a localized message for unavailable content.
      See Also: