Tutorial¶
pyconf
is a very simple configuration tool that performs variable
substitution on a given list of files. It is based on the popular unix-based
Autoconf configuration utility.
The files, with the variables to replace, are identified with a .pin
extension and are never modified by the tool. Upon performing the replacement
a new file is created in the same location as the original but with the
.pin
removed and any variables replaced.
Configuration file¶
The pyconf
configuration file, always named pyconf.yml
, is a
YAML file that lists all the variable substitutions, pairs of name and
values, and the relative path of the files to configure.
It consists of three main sections:
- The first section, named
pyconf
, holds metadata related to the tool itself, such as theversion
, etc. - The second one, named
variables
, lists all the variables and their corresponding values. - The last one, named
files
lists the relative path of the files to perform the substitution. The files are listed without the.pin
extension. This section is optional and, if not present, no replacement will be performed (and a message will be displayed).
Variables¶
Variables in .pin
files are enclosed by the @
character. As such, the
character cannot be present in the variable name.
The name of the variable must be written in upper case and can only contain alphanumeric characters and the underscore.
The value can contain spaces but it will be stripped of any leading/trailing space. If a value is surrounded by quotes, or double quotes, they are removed and what is left becomes the actual value, including spaces.
variables:
VAR_ONE: ' this value hast 3 leading and 3 trailing spaces '
VAR_TWO: " this value hast 3 leading and 3 trailing spaces "
To preserve the quotes as part of the value escape them as \'
.
variables:
VAR_ONE: \' quotes are preserved \'
Quotes are required if the value contains any of these characters: :[]
.
variables:
VAR_ONE: 'the value: 345'
Variable references in values¶
It is possible to construct the value of a variable based on the value of
another variable defined anywhere in the file. This is achieved
by enclosing the variable by ${}
.
variables:
VAR_ONE: value
VAR_TWO: this ${VAR_ONE} uses another variable value
A complete example¶
A typical pyconf.yml
configurationm file is illustrated below.
pyconf:
version: 1.0
author: Alan
date: 2018-07-04
variables:
APPLICATION_NAME: nautilus
APPLICATION_VERSION: 1.0.0
OWNER: alan
EMAIL: alan@gmail.com
SOLUTION_NAME: ${OWNER}-${APPLICATION_NAME}
SOLUTION_VERSION: ${APPLICATION_VERSION}-SNAPSHOT
PRODUCT_NAME: ${OWNER}/${APPLICATION_NAME}
PRODUCT_VERSION: ${APPLICATION_VERSION}.rc1
SOLUTION_PROFILES: '[production]'
files:
- makefile
- REAME.md
- bin/launch.sh
- solution/pom.xml
- config/launch.profile
And, assuming the above pyconf.yml
is in the current working directory,
it is processed by just running pyconf
.
$ pyconf
When used with the following bin/lunch.sh.pin
file
#!/usr/bin/env bash
./@APPLICATION_NAME@
The following bin/launch.sh
will be created
#!/usr/bin/env bash
./nautilus