Doing YAML substitution or preprocessing
Sometimes you could want to change values in the YAML depending on external stuff, or just want to be able to change something for each variant run.
In this case you can use external tools to create various YAML files using a template, but you can also use KiBot’s definitions.
The definitions allows you to replace tags like @VARIABLE@
by some
specified value. These definitions can be specified at the command line
using the -E
option. As an example: -E UNITS=millimeters
will
replace all @UNITS@
markers by millimeters
. This is applied to
all YAML files loaded, so this propagates to all the imported YAML
files.
You can use -E
as many times as you need.
Also note that the --def-from-env
option adds all the environment
variables as definitions.
Default definitions
A configuration file using the @VARIABLE@
tags won’t be usable
unless you provide proper values for all de used variables. When
using various tags this could be annoying. KiBot supports defining
default values for the tags. Here is an example:
kibot:
version: 1
outputs:
- name: 'gerbers_@ID@'
comment: "Gerbers with definitions"
type: gerber
output_id: '_@ID@'
layers: '@LAYERS@'
...
definitions:
ID: def_id
LAYERS: F.Cu
Note that from the YAML point this is two documents in the same file. The second document is used to provide default values for the definitions. As defaults they have the lowest precedence.
Definitions during import
When importing a configuration you can specify values for the
@VARIABLE@
tags. This enables the creation of parametrizable
imports. Using the example depicted in Default
definitions saved to a file named
simple.kibot.yaml you can use:
kibot:
version: 1
import:
- file: simple.kibot.yaml
definitions:
ID: external_copper
LAYERS: "[F.Cu, B.Cu]"
This will import simple.kibot.yaml and use these particular values. Note that they have more precedence than the definitions found in simple.kibot.yaml, but less precedence than any value passed from the command line.
Recursive definitions expansion
When KiBot expands the @VARIABLE@
tags it first applies all the
replacements defined in the command line, and then all the values
collected from the definitions
. After doing a round of replacements
KiBot tries to do another. This process is repeated until nothing is
replaced or we reach 20 iterations. So you can define a tag that
contains another tag.
As an example, if the configuration shown in Definitions during import is stored in a file named top.kibot.yaml you could use:
kibot -v -c top.kibot.yaml -E ID=@LAYERS@
This will generate gerbers for the front/top and bottom layers using [F.Cu, B.Cu] as output id. So you’ll get light_control-B_Cu_[F.Cu, B.Cu].gbr and light_control-F_Cu_[F.Cu, B.Cu].gbr.