Configuration File Syntax

These are the main highlights of the configuration files used in Serge:

• Clean, easy-to-read syntax (don't forget to install a syntax highlighter for your favorite IDE!)
• Flexible inheritance/override mechanism to reuse common settings
• Ability to reference environment variables (reuse the same configuration files in multiple scenarios)
• Schema-based config file validation

Internally, Serge uses Config::Neat library that implements this format, so you can always use its own documentation as an additional source of information about the format and its implementation details.

Tree Structure

Serge configuration file represents a tree structure. There can be sections, nested sub-sections, and parameter-value definitions on each level. Sections are denoted with curly braces. Everything between { and } is considered an inner structure of the section. Section and parameter names technically can consist of any characters except whitespace.

Arrays of Objects

Some sections have an empty name (you can treat these structures as arrays of objects). Consider the following structure, which defines an array of jobs:

For such array entries that originally don't have a name, one can still provide labels: names that start with a colon. Such labels can later help you override parts of the config:

Comments

In addition to single-line comments starting with #, one can define multi-line comments with /* and */:

Boolean Values

Boolean parameters are defined as YES or NO:

You can omit 'YES' value altogether, and use just the paramater name as a flag. The example below is identical to the one above:

Strings

String parameters generally don't have to be wrapped into any quotes. But if the string has leading or trailing spaces, or multiple spaces in between, the string needs to be wrapped with ` symbols (verbatim quotes):

If the string is long, it can spawn multiple lines, provided all lines start at the same character position as the first line. Since whitespace is normalized by default, each line break and its surrounding spaces will be converted to a single space:

Arrays of Strings

Arrays of strings are defined the same way as strings. It's config schema that internally decides whether to treat a parameter as a string or array. Array items are separated by whitespace. If any array item needs to have space in between, or evaluate to a space or an empty value, use verbatim quotes:

Arrays, like strings, can also spawn multiple lines: