# The config system in librnd

## Config file syntax

The config file syntax is lihata. Most users don't need to understand most of the syntax, just follow the patterns seen in the examples. A few thumb of rules:

- structural nodes usually start with a ha: or li: prefix; which one needs to be used is pretty much tied to the node name; thus casual users don't need to care about what they are for, just remember them as part of the name
- non-structural nodes are usually given in the form of name = value; use braces around the value if it contains any non-alphanumeric, non-whitespace character
- list and array members should better be braced
- list and array separator should be semicolon (not comma)

### config root syntax

A librnd config file, (or document for short) has a single root node whose name must be li:pcb-rnd-conf-v1 - this is the signature of the document. It is a flat list of one or more config root/ subtrees. TODO: is this really a list or a hash?

Each config root is a partial description of the config tree (which is the logical configuration of all possible settings). Config roots have a policy and a priority attached. This is done in the name of the config root, which must be of the form of policy-priority, e.g. "overwrite-300" or "append-125". The priority part (with the dash) can be omitted (and then the per role default priority is used), e.g. "overwrite" or "append" are valid config root names.

Under the config root, a tree of sections (hashes) and setting values (text nodes) are built. These structures and values are in 1:1 correspondence with the config tree. Excess (unknown) keys are considered a warning (except in the plugin/ and utils/ subtrees). Missing keys or missing subtrees is normal because a config root can be partial.

TODO: examples

### list syntax

TODO: list syntax

### in project files

TODO