Package org.apache.sis.io

## Class TabularFormat<T>

- Object
- - Format
  - - CompoundFormat<T>
    - - TabularFormat<T>

- Type Parameters:
    `T` - the base type of objects parsed and formatted by this class.
  All Implemented Interfaces:
    `Serializable`, `Cloneable`, `Localized`
  Direct Known Subclasses:
    `FeatureFormat`, `LocationFormat`, `ParameterFormat`, `StatisticsFormat`, `TreeTableFormat`

      public abstract class TabularFormat<T>
      extends CompoundFormat<T>

  Base class for parser and formatter of tabular data, providing control on line and column separators. The line separator is specified by a string. But the column separator is specified by a pattern which provide some control on the character to repeat, and on the strings to insert before and after the repeated character. See the following methods for details:
  - `setLineSeparator(String)`
  - `setColumnSeparatorPattern(String)`
  Note for subclass implementions
  This base class takes care of splitting a column separator pattern into its components (`beforeFill`, `fillCharacter` and `columnSeparator`) for easier usage in `format(…)` method implementations. Subclasses can use those fields like below:

  Formatting table without border:

  >     TableAppender table = new TableAppender(out, "");
  >     // ... do some work, then add a column separator:
  >     table.append(beforeFill);
  >     table.nextColumn(fillCharacter);
  >     table.append(columnSeparator);

  Formatting table with a border:

  >     TableAppender table = new TableAppender(out, columnSeparator);
  >     // ... do some work, then add a column separator:
  >     table.append(beforeFill);
  >     table.nextColumn(fillCharacter);

  Since:
    0.3
  See Also:
    `TableAppender`, Serialized Form

  Defined in the `sis-utility` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class Format

      `Format​.Field`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected String` | `beforeFill` | The string to write before the `fillCharacter`, or an empty string if none.
    `protected String` | `columnSeparator` | The string to write after the `fillCharacter`, or an empty string if none.
    `protected char` | `fillCharacter` | The character to repeat after the content of a cell for alignment with the next column.
    `protected String` | `lineSeparator` | The line separator to use for formatting the tree.
    `protected boolean` | `omitTrailingNulls` | `true` if the trailing `null` values shall be omitted at formatting time.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TabularFormat​(Locale locale, TimeZone timezone)` | Creates a new tabular format.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `TabularFormat<T>` | `clone()` | Returns a clone of this format.
    `protected Matcher` | `getColumnSeparatorMatcher​(CharSequence text)` | Returns a matcher for the column separators in the given text.
    `String` | `getColumnSeparatorPattern()` | Returns the pattern of characters used in column separators.
    `String` | `getLineSeparator()` | Returns the current line separator.
    `void` | `setColumnSeparatorPattern​(String pattern)` | Sets the pattern of the characters to insert between the columns.
    `void` | `setLineSeparator​(String separator)` | Sets the line separator.

    - ### Methods inherited from class CompoundFormat

      `createFormat, format, format, getFormat, getLocale, getLocale, getTimeZone, getValueType, parse, parseObject, parseObject`

    - ### Methods inherited from class Format

      `format, formatToCharacterIterator`

    - ### Methods inherited from class Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### lineSeparator

          protected String lineSeparator

      The line separator to use for formatting the tree. The default value is system-dependent.
      See Also:
        `getLineSeparator()`, `setLineSeparator(String)`

    - #### columnSeparator

          protected String columnSeparator

      The string to write after the `fillCharacter`, or an empty string if none. This is the sequence of characters after the "`[ ]`" pair of brackets in the pattern given to the `setColumnSeparatorPattern(String)` method.

    - #### fillCharacter

          protected char fillCharacter

      The character to repeat after the content of a cell for alignment with the next column. This is the character between the "`[ ]`" pair of brackets in the pattern given to the `setColumnSeparatorPattern(String)` method.

      Subclasses will typically use this value in calls to `TableAppender​.nextColumn(char)`.

    - #### beforeFill

          protected String beforeFill

      The string to write before the `fillCharacter`, or an empty string if none. This is the sequence of characters before the "`[ ]`" pair of brackets in the pattern given to the `setColumnSeparatorPattern(String)` method.

    - #### omitTrailingNulls

          protected boolean omitTrailingNulls

      `true` if the trailing `null` values shall be omitted at formatting time. This flag is controlled by the presence or absence of the `'?'` character at the beginning of the pattern given to the `setColumnSeparatorPattern(String)` method.

  - ### Constructor Detail

    - #### TabularFormat

          public TabularFormat​(Locale locale,
                               TimeZone timezone)

      Creates a new tabular format.
      Parameters:
        `locale` - the locale to use for numbers, dates and angles formatting, or `null` for the root locale.
        `timezone` - the timezone, or `null` for UTC.

  - ### Method Detail

    - #### getLineSeparator

          public String getLineSeparator()

      Returns the current line separator. The default value is system-dependent.
      Returns:
        the current line separator.

    - #### setLineSeparator

          public void setLineSeparator​(String separator)

      Sets the line separator. Can not be a null or empty string.
      Parameters:
        `separator` - the new line separator.

    - #### getColumnSeparatorPattern

          public String getColumnSeparatorPattern()

      Returns the pattern of characters used in column separators. Those characters will be used only if more than one column is formatted. See `setColumnSeparatorPattern(String)` for a description of the pattern syntax.
      Returns:
        the pattern of the current column separator.

    - #### setColumnSeparatorPattern

          public void setColumnSeparatorPattern​(String pattern)
                                         throws IllegalArgumentException

      Sets the pattern of the characters to insert between the columns. The pattern shall contain exactly one occurrence of the `"[ ]"` pair of bracket, with exactly one character between them. This character will be repeated as many time as needed for columns alignment.

      The formatting pattern can optionally be followed by a regular expression to be used at parsing time. If omitted, the parsing pattern will be inferred from the formatting pattern. If specified, then the `parse` method will invoke the `Matcher​.find()` method for determining the column boundaries.

      The characters listed below have special meaning in the pattern. Other characters are appended as-is between the columns.

      Reserved characters
      Character(s) | Meaning
      --- | ---
      `'?'` | Omit the column separator for trailing null values.
      `"[ ]"` | Repeat the character between bracket as needed.
      `'/'` | Separate the formatting pattern from the parsing pattern.
      `'\\'` | Escape any of the characters listed in this table.

      Restrictions
      - If present, `'?'` shall be the first character in the pattern.
      - The repeated character (specified inside the pair of brackets) is mandatory.
      - In the current implementation, the repeated character must be in the Basic Multilanguage Plane.
      - If `'/'` is present, anything on its right side shall be compliant with the `Pattern` syntax.
      Example: The `"?……[…] "` pattern means "If the next value is non-null, then insert the `"……"` string, repeat the `'…'` character as many time as needed (may be zero), then insert a space".
      Parameters:
        `pattern` - the pattern of the new column separator.
      Throws:
        `IllegalArgumentException` - if the given pattern is illegal.

    - #### getColumnSeparatorMatcher

          protected Matcher getColumnSeparatorMatcher​(CharSequence text)

      Returns a matcher for the column separators in the given text. This method is invoked by subclasses in their `parse(…)` implementations.
      Parameters:
        `text` - the text for which to get a matcher.
      Returns:
        a matcher for the column separators in the given text.

    - #### clone

          public TabularFormat<T> clone()

      Returns a clone of this format.
      Overrides:
        `clone` in class `CompoundFormat<T>`
      Returns:
        a clone of this format.