Environment description syntax

The environment descriptions (that can be read by ctpl_environ_add_from_stream() and friends) contains any number of symbol-value pairs that have the following syntax:

1
<symbol> = <value>;

where <symbol> is a valid symbol and <value> is a valid value. Apart the four required parts (symbol, equal sign, value, semicolon), there can be any number of blank characters and comments before, between and after them.

Symbol

The symbol part is composed of any alphanumeric characters and underscore, repeated any number of times.

Value

There are 3 supported value types:

  • Numbers, as read by ctpl_input_stream_read_number().

  • Strings, as read by ctpl_input_stream_read_string_literal().

  • Arrays of any of these 3 types of values. Arrays start with an opening square bracket ([) and end with a closing square bracket (]). The values in the array are separated by a comma (,). There can be any number of values (but at least one), which may be of any type, including arrays as well.

    Example 5. A sample array

    1
    [1, 2, 3, "more", [42, 84, 126]]

Blanks

Blank characters are not interpreted and may appear anywhere nothing is expected, e.g. between the identifier and the equal sign. The blank characters are space, tab, vertical tab, newline and carriage return.

Comments

Comments are special segments that don't get interpreted. Such segments start with a number sign (#) that is not part of any other construct (such as a string literal), and ends at the following end of line.

Comments can be useful to add extra information to explain an element, to separate different parts or to disable a part of the description without actually removing it.

Example 6. A small comment

1
# This is a comment

Example 7. An environment description example

1
2
3
4
5
6
7
8
9
10
11
12
# This is an example that shows some environment description syntax.
# It does not show everything (there are more supported numeric constructs for
# example), but it covers a pretty good part of it.

foo         = "string value";
# This is a comment
bar         = 42; # An important number!
str         = "a more
               complex\" string";
array       = [1, 2, "hello", ["world", "dolly"]];
real_number = 2.12e-9;
hex_number  = 0xffe2; # 65506