uk.ac.starlink.table.formats

## Class AbstractTextTableWriter

- java.lang.Object
- - uk.ac.starlink.table.formats.DocumentedStreamStarTableWriter
  - - uk.ac.starlink.table.formats.AbstractTextTableWriter

- All Implemented Interfaces:
    Documented, DocumentedIOHandler, StarTableWriter
  Direct Known Subclasses:
    AsciiTableWriter, IpacTableWriter, TextTableWriter

      public abstract class AbstractTextTableWriter
      extends DocumentedStreamStarTableWriter

  A `StarTableWriter` which outputs text to a human-readable text file. Table parameters (per-table metadata) can optionally be output as well as the table data themselves.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractTextTableWriter(java.lang.String[] extensions, boolean writeParams)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract java.lang.String` | `formatColumnHeads(int[] colwidths, ColumnInfo[] cinfos)` Returns a string with headings for the table columns.
    `protected abstract java.lang.String` | `formatLine(int[] colwidths, java.lang.String[] data)` Returns a line showing a row of table data.
    `protected abstract java.lang.String` | `formatParam(java.lang.String name, java.lang.String value, java.lang.Class<?> clazz)` Returns a formatted parameter-value pair.
    `protected abstract java.lang.String` | `formatSeparator(int[] colwidths)` Returns a decorative separator line, of the sort you might find between the column headings and the table data.
    `protected abstract java.lang.String` | `formatValue(java.lang.Object val, ValueInfo vinfo, int width)` Formats a data value for output.
    `java.nio.charset.Charset` | `getEncoding()` Returns the character encoding used for output.
    `java.lang.String` | `getFormatName()` Returns "text";
    `int` | `getMaximumParameterLength()` Returns the maximum length for the value of a parameter as passed to `formatParam(java.lang.String, java.lang.String, java.lang.Class<?>)`.
    `int` | `getMaxWidth()` Returns the maximum width for any output column.
    `java.lang.String` | `getMimeType()` Returns a string suitable for use as the value of a MIME Content-Type header.
    `int` | `getMinNameWidth(ColumnInfo info)` Returns the minimum width required to output the actual characters of the name for a given column.
    `int` | `getSampledRows()` Returns the number of rows which will be sampled to work out the column width.
    `boolean` | `getWriteParameters()` Finds out whether the output will include table parameters.
    `void` | `setEncoding(java.nio.charset.Charset encoding)` Sets the character encoding for output text.
    `void` | `setMaximumParameterLength(int maxParamLength)` Sets the maximum length for the value of a parameter that will be output.
    `void` | `setMaxWidth(int maxWidth)` Sets the maximum width in characters for any output column.
    `void` | `setSampledRows(int sampledRows)` Sets the number of rows which will be sampled before output is commenced to work out the column widths.
    `void` | `setWriteParameters(boolean writeParams)` Set whether the output should include table parameters.
    `void` | `writeStarTable(StarTable startab, java.io.OutputStream strm)` Writes a `StarTable` object to a given output stream.

    - ### Methods inherited from class uk.ac.starlink.table.formats.DocumentedStreamStarTableWriter

      `getExtensions, looksLikeFile, writeStarTable`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface uk.ac.starlink.table.formats.DocumentedIOHandler

      `docIncludesExample, matchesExtension, readText, toLink`

    - ### Methods inherited from interface uk.ac.starlink.table.Documented

      `getXmlDescription`

- - ### Constructor Detail

    - #### AbstractTextTableWriter

          protected AbstractTextTableWriter(java.lang.String[] extensions,
                                            boolean writeParams)

      Constructor.
      Parameters:
        `extensions` - list of lower-cased filename extensions, excluding the '.' character
        `writeParams` - whether parameters will be written by default

  - ### Method Detail

    - #### getFormatName

          public java.lang.String getFormatName()

      Returns "text";
      Returns:
        "text"

    - #### getMimeType

          public java.lang.String getMimeType()

      Description copied from interface: `StarTableWriter`
      Returns a string suitable for use as the value of a MIME Content-Type header. If no suitable MIME type is available or known, one of "`application/octet-stream`" (for binary formats) or "`text/plain`" for ASCII ones) is recommended.
      Returns:
        MIME content type

    - #### writeStarTable

          public void writeStarTable(StarTable startab,
                                     java.io.OutputStream strm)
                              throws java.io.IOException

      Description copied from interface: `StarTableWriter`
      Writes a `StarTable` object to a given output stream. The implementation can assume that `out` is suitable for direct writing (for instance it should not normally wrap it in a `BufferedOutputStream`), and should not close it at the end of the call.

      Not all table writers are capable of writing to a stream; an implementation may throw a `TableFormatException` to indicate that it cannot do so.

      Parameters:
        `startab` - the table to write
        `strm` - the output stream to which `startab` should be written
      Throws:
        `TableFormatException` - if this table cannot be written to a stream
        `java.io.IOException` - if there is some I/O error

    - #### setMaximumParameterLength

          @ConfigMethod(property="maxParam",
                        sequence=30,
                        example="320",
                        doc="<p>Maximum width in characters of an output table parameter. Parameters with values longer than this will be truncated.</p>")
          public void setMaximumParameterLength(int maxParamLength)

      Sets the maximum length for the value of a parameter that will be output.
      Parameters:
        `maxParamLength` - maximum printable parameter length

    - #### getMaximumParameterLength

          public int getMaximumParameterLength()

      Returns the maximum length for the value of a parameter as passed to `formatParam(java.lang.String, java.lang.String, java.lang.Class<?>)`. The default implementation currently returns 160.
      Returns:
        maximum length for output string parameters

    - #### setWriteParameters

          @ConfigMethod(property="params",
                        sequence=10,
                        doc="<p>Whether to output table parameters as well as row data.</p>")
          public void setWriteParameters(boolean writeParams)

      Set whether the output should include table parameters. If so they are written as name:value pairs one per line before the start of the table proper.
      Parameters:
        `writeParams` - true iff you want table parameters to be output as well as the table data

    - #### getWriteParameters

          public boolean getWriteParameters()

      Finds out whether the output will include table parameters.
      Returns:
        true iff the table parameters will be output as well as the table data

    - #### setMaxWidth

          @ConfigMethod(property="maxCell",
                        sequence=20,
                        example="320",
                        doc="<p>Maximum width in characters of an output table cell. Cells longer than this will be truncated.</p>")
          public void setMaxWidth(int maxWidth)

      Sets the maximum width in characters for any output column. Values longer than this may be truncated.
      Parameters:
        `maxWidth` - maximum column value width in characters

    - #### getMaxWidth

          public int getMaxWidth()

      Returns the maximum width for any output column. Values longer than this may be truncated.
      Returns:
        maximum permitted column width in characters

    - #### getMinNameWidth

          public int getMinNameWidth(ColumnInfo info)

      Returns the minimum width required to output the actual characters of the name for a given column. Padding applied subsequently by this object's `formatColumnHeads(int[], uk.ac.starlink.table.ColumnInfo[])` method does not need to be included.
      Parameters:
        `info` - column metadata
      Returns:
        minimum number of characters required for column title

    - #### setSampledRows

          @ConfigMethod(property="sampledRows",
                        example="10000",
                        sequence=15,
                        doc="<p>The number of rows examined on a first pass of the table to determine the width of each column. Only a representative number of rows needs to be examined, but if a formatted cell value after this limit is wider than the cells up to it, then such later wide cells may get truncated. If the value is &lt;=0, all rows are examined in the first pass; this is the default, but it can be configured to some other value if that takes too long.</p>")
          public void setSampledRows(int sampledRows)

      Sets the number of rows which will be sampled before output is commenced to work out the column widths.
      Parameters:
        `sampledRows` - number of rows to be sampled

    - #### getSampledRows

          public int getSampledRows()

      Returns the number of rows which will be sampled to work out the column width.
      Returns:
        number of rows scanned

    - #### setEncoding

          @ConfigMethod(property="encoding",
                        sequence=100,
                        usage="ASCII|UTF-8|UTF-16|...",
                        example="UTF-16",
                        doc="<p>Specifies the character encoding used in the output file.\n</p>")
          public void setEncoding(java.nio.charset.Charset encoding)

      Sets the character encoding for output text.
      Parameters:
        `encoding` - character encoding

    - #### getEncoding

          public java.nio.charset.Charset getEncoding()

      Returns the character encoding used for output.
      Returns:
        character encoding

    - #### formatValue

          protected abstract java.lang.String formatValue(java.lang.Object val,
                                                          ValueInfo vinfo,
                                                          int width)

      Formats a data value for output.
      Parameters:
        `val` - the value
        `vinfo` - the metadata object describing `val`'s type
        `width` - maximum preferred width into which the value should be formatted
      Returns:
        formatted string meaning `value`, preferably no longer than `width` characters

    - #### formatSeparator

          protected abstract java.lang.String formatSeparator(int[] colwidths)

      Returns a decorative separator line, of the sort you might find between the column headings and the table data.
      Parameters:
        `colwidths` - column widths in characters
      Returns:
        separator line including any line end characters

    - #### formatColumnHeads

          protected abstract java.lang.String formatColumnHeads(int[] colwidths,
                                                                ColumnInfo[] cinfos)

      Returns a string with headings for the table columns.
      Parameters:
        `colwidths` - column widths in characters
        `cinfos` - array of column headings
      Returns:
        headings line including any line end characters

    - #### formatLine

          protected abstract java.lang.String formatLine(int[] colwidths,
                                                         java.lang.String[] data)

      Returns a line showing a row of table data.
      Parameters:
        `colwidths` - column widths in characters
        `data` - array of strings to be output, one per column
      Returns:
        data line including any line end characters

    - #### formatParam

          protected abstract java.lang.String formatParam(java.lang.String name,
                                                          java.lang.String value,
                                                          java.lang.Class<?> clazz)

      Returns a formatted parameter-value pair.
      Parameters:
        `name` - parameter name
        `value` - formatted parameter value
        `clazz` - type of value
      Returns:
        parameter line including any line end characters