uk.ac.starlink.table.formats

## Class AsciiStarTable

- java.lang.Object
- - uk.ac.starlink.table.AbstractStarTable
  - - uk.ac.starlink.table.formats.StreamStarTable
    - - uk.ac.starlink.table.formats.AsciiStarTable

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, StarTable

      public class AsciiStarTable
      extends StreamStarTable

  Simple ASCII-format table. This reader attempts to make sensible decisions about what is a table and what is not, but inevitably it will not be able to read ASCII tables in any format.

  Here are the rules:

  - Bytes in the file are interpreted as ASCII characters
  - Each table row is represented by a single line of text
  - Lines are terminated by one or more contiguous line termination characters: line feed (0x0A) or carriage return (0x0D)
  - Within a line, fields are separated by one or more whitespace characters: space (" ") or tab (0x09)
  - A field is either an unquoted sequence of non-whitespace characters, or a sequence of non-newline characters between matching single (') or double (") quote characters - spaces are therefore allowed in quoted fields
  - Within a quoted field, whitespace characters are permitted and are treated literally
  - Within a quoted field, any character preceded by a backslash character ("\") is treated literally. This allows quote characters to appear within a quoted string.
  - An empty quoted string (two adjacent quotes) or the string "`null`" (unquoted) represents the null value
  - All data lines must contain the same number of fields (this is the number of columns in the table)
  - The data type of a column is guessed according to the fields that appear in the table. If all the fields in one column can be parsed as integers (or null values), then that column will turn into an integer-type column. The types that are tried, in order of preference, are: `Boolean`, `Short` `Integer`, `Long`, `Float`, `Double`, `String`
  - Empty lines are ignored
  - Anything after a hash character "#" (except one in a quoted string) on a line is ignored as far as table data goes; any line which starts with a "!" is also ignored. However, lines which start with a "#" or "!" at the start of the table (before any data lines) will be interpreted as metadata as follows:
    - The last "#"/"!"-starting line before the first data line may contain the column names. If it has the same number of fields as there are columns in the table, each field will be taken to be the title of the corresponding column. Otherwise, it will be taken as a normal comment line.
    - Any comment lines before the first data line not covered by the above will be concatenated to form the "description" parameter of the table.

- - ### Field Summary

    - ### Fields inherited from class uk.ac.starlink.table.formats.StreamStarTable

      `END`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AsciiStarTable(DataSource datsrc)` Constructor with default options.
    `AsciiStarTable(DataSource datsrc, java.nio.charset.Charset encoding, int maxSample, RowEvaluator.Decoder<?>[] decoders)` Constructor with configuration option.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected RowEvaluator.Metadata` | `obtainMetadata()` Obtains column metadata for this table, probably by reading through the rows once and using a RowEvaluator.
    `protected java.util.List<java.lang.String>` | `readRow(java.io.BufferedReader in)` Reads the next row of data from a given stream.

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

      `getColumnCount, getColumnInfo, getReader, getRowCount, getRowSequence, init`

    - ### Methods inherited from class uk.ac.starlink.table.AbstractStarTable

      `checkedLongToInt, close, getCell, getColumnAuxDataInfos, getName, getParameters, getRow, getRowAccess, getRowSplittable, getURL, isRandom, setName, setParameters, setURL`

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

      `getParameterByName, setParameter`

- - ### Constructor Detail

    - #### AsciiStarTable

          public AsciiStarTable(DataSource datsrc)
                         throws TableFormatException,
                                java.io.IOException

      Constructor with default options.
      Parameters:
        `datsrc` - the data source containing the table text
      Throws:
        `TableFormatException` - if the input stream doesn't appear to form a ASCII-format table
        `java.io.IOException` - if some I/O error occurs

    - #### AsciiStarTable

          public AsciiStarTable(DataSource datsrc,
                                java.nio.charset.Charset encoding,
                                int maxSample,
                                RowEvaluator.Decoder<?>[] decoders)
                         throws TableFormatException,
                                java.io.IOException

      Constructor with configuration option.
      Parameters:
        `datsrc` - the data source containing the table text
        `encoding` - character encoding
        `maxSample` - maximum number of rows sampled to determine column data types; if <=0, all rows are sampled
        `decoders` - permitted data type decoders
      Throws:
        `TableFormatException` - if the input stream doesn't appear to form a ASCII-format table
        `java.io.IOException` - if some I/O error occurs

  - ### Method Detail

    - #### obtainMetadata

          protected RowEvaluator.Metadata obtainMetadata()
                                                  throws TableFormatException,
                                                         java.io.IOException

      Description copied from class: `StreamStarTable`
      Obtains column metadata for this table, probably by reading through the rows once and using a RowEvaluator.
      Specified by:
        `obtainMetadata` in class `StreamStarTable`
      Returns:
        information about the table represented by the character stream
      Throws:
        `TableFormatException` - if the data doesn't represent this kind of table
        `java.io.IOException` - if I/O error is encountered

    - #### readRow

          protected java.util.List<java.lang.String> readRow(java.io.BufferedReader in)
                                                      throws java.io.IOException

      Reads the next row of data from a given stream. Ignorable rows are skipped; comments may be stashed away.
      Specified by:
        `readRow` in class `StreamStarTable`
      Parameters:
        `in` - input stream
      Returns:
        list of Strings one for each cell in the row, or `null` for end of stream
      Throws:
        `TableFormatException` - if the data doesn't represent this kind of table
        `java.io.IOException` - if I/O error is encountered