Next Previous Up Contents
Next: Comma-Separated Values
Up: Supplied Output Handlers
Previous: Feather

#### 3.7.6 ASCII

Writes to a simple plain-text format intended to be comprehensible by humans or machines. Despite the name, it can be configured to write non-ASCII Unicode characters by setting the `encoding` option.

The first line is a comment, starting with a "`#`" character, naming the columns, and an attempt is made to line up data in columns using spaces. No metadata apart from column names is written.

The handler behaviour may be modified by specifying one or more comma-separated name=value configuration options in parentheses after the handler name, e.g. "`ascii(params=false,sampledRows=10000)`". The following options are available:

`params = true|false`
  Whether to output table parameters as well as row data. (Default: `false`)
`sampledRows = <int>`
  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 <=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. (Default: `0`)
`maxCell = <int>`
  Maximum width in characters of an output table cell. Cells longer than this will be truncated. (Default: `158`)
`maxParam = <int>`
  Maximum width in characters of an output table parameter. Parameters with values longer than this will be truncated. (Default: `160`)
`encoding = ASCII|UTF-8|UTF-16|...`
  Specifies the character encoding used in the output file. (Default: `US-ASCII`)

If no output format is explicitly chosen, writing to a filename with the extension "`.txt`" (case insensitive) will select `ascii` format for output.

An example looks like this:

    # RECNO SPECIES   NAME          LEGS HEIGHT MAMMAL
      1     pig       "Pigling Bland" 4    0.8    true
      2     cow       Daisy         4    2.0    true
      3     goldfish  Dobbin        ""   0.05   false
      4     ant       ""            6    0.001  false
      5     ant       ""            6    0.001  false
      6     "queen ant" "Ma\'am"      6    0.002  false
      7     human     Mark          2    1.8    true

The handler class for this format is `AsciiTableWriter`.

Next Previous Up Contents
Next: Comma-Separated Values
Up: Supplied Output Handlers
Previous: Feather

STIL - Starlink Tables Infrastructure Library
Starlink User Note252
STIL web page: http://www.starlink.ac.uk/stil/
Author email: m.b.taylor@bristol.ac.uk