Configuration file

From TargetWiki

Targetware uses configuration files in a number of places, and they are all of a standard format. This format mirrors the layout of a Lua table, with some restrictions: a configuration file can only support keys in a table that are either numbers or strings, and can only support values that are nil, booleans, numbers, strings, or other tables.

Contents 1 Format 1.1 Keys 1.2 Values 2 Includes 3 Comments 4 Example

Format

Each configuration file is essentially a table. Each entry in the table is a key-value pair.

Keys

Keys can be unquoted strings, in which case they must start with a letter or an underscore and consist only of letters, numbers and underscores, or quoted strings, in which case they can consist of anything. If a value is present with no key, it is assigned to the next available numerical array index.

Values

Each entry can have one of five types of value:

nil

The literal word nil, with no quotes, indicates a nil value.

boolean

The literal words true and false, with no quotes, indicate a boolean value.

number

A number, either with a decimal point or without, and possibly with a negative sign in front of it, is treated as a numeric value. Again, it should not be in quotes.

string

Anything inside double quotes, "like this", is treated as a string value. This can include any UTF-8 string, as well as allowing escaped values for non-printable characters. The C style escapes of \t for a tab, \n for a newline, \r for a carriage return, \" for a double quote inside a string, and \\ for a backslash are accepted.

table

A table is indicated by curly braces, like this: { }. Any type of value that could go in the main table of the configuration file can go in a sub-table, either with a string for a key, or with no key (and thus assigned to an array index).

Includes

Configuration files also have a feature that isn't present in Lua tables: includes. At any point in a configuration file, a statement such as this can appear:

include "filename"

This will cause the configuration file, when loaded, to reference the specified file and include its contents as entries in the current configuration file right at the point the include statement appears. This allows included files to appear anywhere, including nested in tables.

Comments

Comments can be inserted in a configuration file. Any line that starts with # or // will be ignored when the file is loaded. Any block enclosed in a /* */ pair will also be ignored. If you load a configuration file into a Lua script with table.read(), all comments will be lost, since Lua has no way of representing them in a table. If you then write that configuration file out again, using table.write(), the resulting file will have no comments in it.

Example

Here's an example configuration file, showing all of the possible variations:

key = nil
another_key = true
"a third key" = false
a_useful_number = -123.456
# This is a comment and will be ignored
"5th key is a string" = "This is a Haiku.\r\nIt is broken into lines.\r\nIt shows off escapes.\r\n"
a_table =
{
    a = true
    b = false
    /*
    the following table is valid, but won't be loaded since it's in a comment block
    a_table_used_as_an_array = { 1 2 3 "foo" nil false }
    */
    "a mixed table" =
    {
        100
        200
        300
        // We're about to include another file, but this is a comment
        include "another_config_file.txt"
        key = "Value"
    }
}

Note that the contents of the file "another_config_file.txt" will be included as elements in the table called "a_mixed_table".