SWI-Prolog -- new

Documentation
- Reference manual
- Packages
  - Managing external tables for SWI-Prolog
    - Managing external tables
      - Creating and destroying tables
        
        new_table/4
        
        open_table/1
        
        close_table/1
        
        free_table/1

Availability::- use_module(library(table)).(can be autoloaded)

new_table(+File, +Columns, +Options, -Handle)

Create a description of a new table, stored in File. Columns is a list of descriptions for each column. A column description is of the form

ColumnName(Type [, ColumnOptions])

Type denotes the Prolog type to which the field should be converted and is one of:

`integer`	Convert to a Prolog integer. The input is treated as a decimal number.
`hexadecimal`	Convert to a Prolog integer. The input is treated as a hex number.
`float`	Convert to a Prolog floating point number. The input is handled by the C-library function `strtod()`.
`atom`	Convert to a Prolog atom.
`string`	Convert to a SWI-Prolog string object.
`code_list`	Convert to a list of ASCII codes.

ColumnOptions is a list of additional properties of the column. Supported values are:

`sorted`	The field is strictly sorted, but may have (adjacent) duplicate entries. If the field is textual, it should be sorted alphabetically, otherwise it should be sorted numerically.
`sorted(+Table)`	The (textual) field is sorted using the ordering declared by the named ordering table. This option may be used to define reverse order, `dictionary' order or other irregular alphabetical ordering. See new_order_table/2.
`unique`	This column has distinct values for each row in the table.
`downcase`	Map all uppercase in the field to lowercase before converting to a Prolog atom, string or code_list.
`map_space_to_underscore`	Map spaces to underscores before converting to a Prolog atom, string or code_list.
`syntax`	For numerical fields. If the field does not contain a valid number, matching the value fails. Reading the value returns the value as an atom.
`width(+Chars)`	Field has fixed width of the specified number of characters. The column-separator is not considered for this column.
`arg(+Index)`	For read_table_record/4, unify the field with the given argument of the record term. Further fields will be assigned index+1, ... .
`skip`	Don't convert this field to Prolog. The field is simply skipped without checking for consistency.

The Options argument is a list of global options for the table. Defined options are:

`record_separator(+Code)`	Character (ASCII) value of the character separating two records. Default is the newline (ASCII 10).
`field_separator(+Code)`	Character (ASCII) value of the character separating two fields in a record. Default is the space (ASCII 32), which also has a special meaning. Two fields separated by a space may be separated by any non-empty sequence of spaces and tab (ASCII 9) characters. For all other separators, a single character separates the fields.
`encoding(+Encoding)`	Text encoding of the file. Values are `iso_latin_1` (default), `utf8` or `native`. The latter uses the native multibyte to unicode conversion.
`escape(+Code, +ListOfMap)`	Sometimes, a table defines escape sequences to make it possible to use the separator-characters in text-fields. This options provides a simple way to handle some standard cases. `Code` is the ASCII code of the character that leads the escape sequence. The default is `-1`, and thus never matched. `ListOfMap` is a list of `From` `=` `To` character mappings. The default map table is the identity map, unless `Code` refers to the `\` character, in which case `\b`, `\e`, `\n`, `\r` and `\t` have their usual meaning.
`functor(+Head)`	Functor used by read_table_record/4. Default is `record` using the maximal argument index of the fields as arity.

If the options are parsed successfully, Handle is unified with a term that may be used as a handle to the table for future operations on it. Note that new_table/4 does not access the file system, so its success only indicates the description could be parsed, not the presence, access or format of the file.