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

  Defined in the `sis-utility` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected 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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### out

          protected final Appendable out

      The underlying character output stream or buffer.

  - ### Constructor Detail

    - #### 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 Detail

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