pungi/doc/format.rst
Lubomír Sedlář 2a8d7f8843 docs: Document config file format
Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com>
2017-06-19 10:51:31 +02:00

91 lines
2.5 KiB
ReStructuredText

==================
Config file format
==================
The configuration file parser is provided by `kobo
<https://github.io/release-engineering/kobo>`_
The file follows a Python-like format. It consists of a sequence of variables
that have a value assigned to them. ::
variable = value
The variable names must follow the same convention as Python code: start with a
letter and consist of letters, digits and underscores only.
The values can be either an integer, float, boolean (``True`` or ``False``), a
string or ``None``. Strings must be enclosed in either single or double quotes.
Complex types are supported as well.
A list is enclosed in square brackets and items are separated with commas.
There can be a comma after the last item as well. ::
a_list = [1,
2,
3,
]
A tuple works like a list, but is enclosed in parenthesis. ::
a_tuple = (1, "one")
A dictionary is wrapped in brackets, and consists of ``key: value`` pairs
separated by commas. The keys can only be formed from basic types (int, float,
string). ::
a_dict = {
'foo': 'bar',
1: None
}
The value assigned to a variable can also be taken from another variable. ::
one = 1
another = one
Anything on a line after a ``#`` symbol is ignored and functions as a comment.
Importing other files
=====================
It is possible to include another configuration file. The files are looked up
relative to the currently processed file.
The general structure of import is: ::
from FILENAME import WHAT
The ``FILENAME`` should be just the base name of the file without extension
(which must be ``.conf``). ``WHAT`` can either be a comma separated list of
variables or ``*``. ::
# Opens constants.conf and brings PI and E into current scope.
from constants import PI, E
# Opens common.conf and brings everything defined in that file into current
# file as well.
from common import *
.. note::
Pungi will copy the configuration file given on command line into the
``logs/`` directory. Only this single file will be copied, not any included
ones. (Copying included files requires a fix in kobo library.)
The JSON-formatted dump of configuration is correct though.
Formatting strings
==================
String interpolation is available as well. It uses a ``%``-encoded format. See
Python documentation for more details. ::
joined = "%s %s" % (var_a, var_b)
a_dict = {
"fst": 1,
"snd": 2,
}
another = "%(fst)s %(snd)s" % a_dict