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

Author:
  Mark Taylor (Starlink)

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`AbstractTextTableWriter(String[] extensions, boolean writeParams)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected abstract String`
`formatValue(Object val, ValueInfo vinfo, int width)`
Formats a data value for output.
`protected byte[]`
`getBytes(String str)`
Returns a byte array corresponding to a given string.
`String`
`getFormatName()`
Returns "text";
`int`
`getMaximumParameterLength()`
Returns the maximum length for the value of a parameter as passed to `printParam(OutputStream, String, String, Class)`.
`int`
`getMaxWidth()`
Returns the maximum width for any output column.
`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.
`protected abstract void`
`printColumnHeads(OutputStream strm, int[] colwidths, ColumnInfo[] cinfos)`
Outputs headings for the table columns.
`protected abstract void`
`printLine(OutputStream strm, int[] colwidths, String[] data)`
Outputs a line of table data.
`protected abstract void`
`printParam(OutputStream strm, String name, String value, Class<?> clazz)`
Outputs a parameter and its value.
`protected abstract void`
`printSeparator(OutputStream strm, int[] colwidths)`
Outputs a decorative separator line, of the sort you might find between the column headings and the table data.
`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, OutputStream strm)`
Writes a `StarTable` object to a given output stream.

### Methods inherited from class DocumentedStreamStarTableWriter

`getExtensions, looksLikeFile, writeStarTable`

### Methods inherited from class Object

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

### Methods inherited from interface Documented

`getXmlDescription`

### Methods inherited from interface DocumentedIOHandler

`docIncludesExample, readText`

## Constructor Details

### AbstractTextTableWriter

protected AbstractTextTableWriter(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 Details

### getFormatName

public String getFormatName()
Returns "text";

Returns:
  "text"

### getMimeType

public 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, OutputStream strm) throws 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:
  `IOException` - if there is some I/O error

### setMaximumParameterLength

@ConfigMethod(property="maxParam", 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 `printParam(OutputStream, String, String, Class)`. The default implementation currently returns 160.

Returns:
  maximum length for output string parameters

### setWriteParameters

@ConfigMethod(property="params", 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", 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 `printColumnHeads(OutputStream, int[], 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", 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

### formatValue

protected abstract String formatValue(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

### printSeparator

protected abstract void printSeparator(OutputStream strm, int[] colwidths) throws IOException
Outputs a decorative separator line, of the sort you might find between the column headings and the table data.

Parameters:
  `strm` - stream to write into
  `colwidths` - column widths in characters
Throws:
  `IOException`

### printColumnHeads

protected abstract void printColumnHeads(OutputStream strm, int[] colwidths, ColumnInfo[] cinfos) throws IOException
Outputs headings for the table columns.

Parameters:
  `strm` - stream to write into
  `colwidths` - column widths in characters
  `cinfos` - array of column headings
Throws:
  `IOException`

### printLine

protected abstract void printLine(OutputStream strm, int[] colwidths, String[] data) throws IOException
Outputs a line of table data.

Parameters:
  `strm` - stream to write into
  `colwidths` - column widths in characters
  `data` - array of strings to be output, one per column
Throws:
  `IOException`

### printParam

protected abstract void printParam(OutputStream strm, String name, String value, Class<?> clazz) throws IOException
Outputs a parameter and its value.

Parameters:
  `strm` - stream to write into
  `name` - parameter name
  `value` - formatted parameter value
  `clazz` - type of value
Throws:
  `IOException`

### getBytes

protected byte[] getBytes(String str)
Returns a byte array corresponding to a given string.

Parameters:
  `str` - string to decode