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:

- `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.

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 `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

- ## Field Summary

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

- ## Constructor Summary

  Constructors
  Constructor
  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.

- ## Method Summary

  Modifier and Type
  Method
  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.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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:
    - `setMaximalLineLength(int)`
    - `setTabulationExpanded(boolean)`
    - `setLineSeparator(String)`
    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.
      `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.

  - ### 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.
      `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.

- ## 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:
      `IllegalArgumentException` - if `tabWidth` 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:
      `lineSeparator` - the new line separator, or `null` for forwarding EOL as-is.
    See Also:
      - `Characters​.isLineOrParagraphSeparator(int)`

  - ### 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 `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.
    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 `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()`.

    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:
      `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.
    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(CharSequence, 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:
      `toString` in class `Object`
    Returns:
      the content of this `Appendable`, or a localized message for unavailable content.
    See Also:
      - `IO​.content(Appendable)`