Configuration Files

Basics

Configuration files are text files that store setting values. They can use two syntaxes (two formats):

• TDD: This is the preferred format.
• Java "Properties": This is mostly supported for backward compatibility with the FMPP 0.8.X series.

The syntax that a configuration file uses is detected with the file extension. For "properties" configuration files, the file extension must be cfg or properties. For TDD files, the preferred file extension is fmpp, but it can be anything but cfg and properties.

When you want to load a configuration file, you specify the path of the file for the front-end somehow (read the documentation of the front-end). But if the configuration file name is one of these standard names:

• config.fmpp
• fmpp.cfg

then it is enough to give the path of the directory that contains the configuration file. (config.fmpp has higher priority if both file is present.)

The configuration base

The configuration base is the directory used as base for resolving relative real paths in setting values. Be default, the configuration base is the directory that contains the configuration file. For example, if /home/me/project1/config.fmpp contains sourceRoot: src, then the sourceRoot will be /home/me/project1/src.

The configuration base can be changed with the configurationBase meta setting. For example, if in the previous example config.fmpp contains configurationBase: ../project2, then the sourceRoot will be /home/me/project2/src. The configurationBase setting applies only for the setting values specified in the same file it is stored in.

Not all relative paths in settings are resolved relatively to the configurationBase. Relative virtual paths, for example, are relative to the sourceRoot or outputRoot. Relative paths of data files passed to data loaders are relative to the dataRoot.

If the setting value comes not from a configuration file (such as from a command-line argument), then the front-end specifies what the configuration base is for that setting value (see the documentation of the front-end).

Configuration inheritance

A configuration file can inherit setting values from another configuration file, with the inheritConfiguration meta setting. When the FMPP core loads a configuration file, and it finds inheritConfiguration setting in it, it will automatically load that configuration file too, and then merge its settings with the settings loaded from the inheriting (the first) configuration file. The settings stored in the inheriting configuration file have higher priority than the settings stored in the inherited configuration file. Thus, if both file contains the same setting, then the value stored in the inheriting file will be used, or it will be merged with the other value if the setting supports merging.

The above description is applicable recursively. That is, an inherited configuration file can inherit another configuration file, and that can inherit yet another configuration file, and so on.

Meta settings (as inheritConfiguration and configurationBase) are never inherited. They influence only the file where they are actually present.

A possible usage of configuration inheritance is to customize a common configuration file. See: <FMPP>/docs/examples/inherit_config.

Configuration files with TDD syntax

These files start in TDD hash mode. For example:

sourceRoot: src
outputRoot: out
data: {tdd(data/style.tdd), birds:csv(data/birds.csv)}
removeExtensions: [ftl, t2]
datetimeFormat: "MMM d, yyyy hh:mm a zzz"
caseSensitive

According the TDD syntax, values of type sequence (as removeExtensions) was put into square brackets. However, for sequence settings, if the sequence would contain exactly 1 element, then you can just give that element directly:

removeExtensions: ftl

and the value will be automatically converted to a sequence that contains the a single string ftl, as it is known that removeExtensions must be a sequence. This is a feature of the setting handling mechanism, not TDD, so don't try to use this trick elsewhere.

TDD configuration files always use ISO-8859-1 encoding, if there is no other encoding suggested in the file with TDD's encoding comment.

For more information about TDD, please read the chapter about TDD.

Configuration files with "properties" syntax

Attention: "properties" configuration files must use cfg or properties file extension.

This is the previous example configuration file with "properties" format:

sourceRoot = src
outputRoot = out
data = tdd(data/style.tdd), birds:csv(data/birds.csv)
removeExtensions = ftl, t2
datetimeFormat = MMM d, yyyy hh:mm a zzz
caseSensitive

The differences to TDD configuration files are:

• It uses "properties" syntax...
• The values do not use TDD syntax, except for composite types as hashes and sequences. For example, the value of datetimeFormat is not quoted (in TDD it was, as the string contains spaces and coma), it is just entered directly.
• The { and } for the data hash and the [ and ] for the removeExtensions sequence is omitted. This is because the value of a hash setting is parsed as hash mode TDD, and the value of a sequence setting is parsed as sequence mode TDD, so the brackets are implied.
• For boolean settings, empty-string is considered as true (see the line that sets caseSensitive).
• Setting names can be written with lower case dashed form (as output-root) instead of mixed case (as outputRoot). This is for backward compatibility with FMPP 0.8.X, where configuration files were use to store options to the command-line tool. The two forms can be used mixed in the same configuration file.

Otherwise "properties" configuration files work in the same way as TDD configuration files. For example, they can inherit an other configuration file. It is not a problem if a "properties" configuration file inherits TDD configuration file or the opposite.