TOML Syntax

The format of the configuration description looks a bit like older Windows INI files, but is actually the TOML format. (TOML was invented by the guy who also invented GitHub, the site you are on right now. Thanks Tom!)

You won't really need to understand the inner workings of TOML in order to use the Tabular CSV plugin. Instead you'll just need to read through these wiki Examples, find something similar to your data, and modify the configuration from there.

The TOML syntax is quite forgiving and yet still concise. It is much easier for non-programmers to edit vs. more widely used formats like JSON or XML, which can both be quite finicky for humans.

The TOML files used by the Tabular CSV plugin have the following characteristics:

• A TOML file is a text file, encoded in UTF-8, so any modern language is supported.
• The file consists of [named sections] and <property> = <value> lines.
• The property = value lines apply to most recent [named section].
• The spaces on either side of the = are optional. Value = 12.5 and Value=12.5 represent the same number.
• If no named section has been encountered yet, the property = value line applies to the default section.
• The default section for the Tabular CSV plugin is the Configuration object.
• Blank lines and whitespace are ignored.
• The # character starts a comment which extends to the end of the line.

Some useful characteristics about properties:

• Property values can be numbers, boolean values true or false, or quoted strings.
• Quoted strings can be enclosed in either single quotes (preferred) or double quotes. See this section for details.
• A property can be set only once per configuration. If you accidentally copy and paste a property = value line in the same section, your configuration will be reported as invalid.

The Tabular CSV plugin adds some improvements on top of regular TOML, to make your integration even more robust:

• property names are case-insensitive. Location = '@Location' and LOCATION="@Location" refer to same property.
• Most of the 200+ properties supported by the plugin do not need to be referenced in the configuration at all. Only specify the columns you need to import.

# Comments are a nice way to document the "magic" of your particular configuration

# Here we the @columnName shorthand string syntax to extract data from the CVS column named 'Location'
Location = '@Location'

# And here we pull the timestamp from the 2nd CSV column, no matter what its name is. This might be brittle!
Time = 2

TOML strings

TOML strings can be either a single quoted string (the preferred form, called a "literal string" in the TOML spec) or a double-quoted string )called a "basic string" in the TOML spec).

The quote character you use at the start of the string must be used at the end of the string.

# These two string definitions are equivalent. They just use different quoting styles.

SomeProperty = 'Some Value' # A literal string in single quotes. The preferred format for Tabular configurations.
SomeProperty = "Some Value" # A basic string in double quotes, which treats a backslash as "special"

The official TOML guide has very good examples of the differences between literal and basic strings.

The single-quote form is preferred over the double-quote form because the double-quote form treats the backslash character \ as a special character, used to escape certain values. A Tabular configuration will not need that functionality, so all the examples in this wiki will use the single-quote form, to reduce the likelihood of copy-and-paste errors giving you grief later on.

Strings can contain any valid Unicode character, including emojis.

Comment = "This measurement was bad! 💩" # OK, this is valid, but is it a good thing or a bad thing?

Strings can also span multiple lines if surrounded by triple single or triple double quotes.

# Import your novel as a comment.
Comment = '''
It was a dark and stormy night.
The sea was calm.

But wait! What is that I see on the horizon?

... To be continued ...
'''

Multiline strings can be useful to document complex PrefaceRegex patterns.