The .cylc File Format
Cylc global and workflow configuration files are written in a nested INI-based format.
Syntax
- Comments
Comments follow a
#
character.- Settings
Configuration items (settings) are written as
key = value
pairs, and can be contained within sections. Setting names (the keys) may contain spaces.- String Values
Quoting single-line string values is optional:
[animals] cat = dusty dog = "fido" # or single quotes: 'fido'
Multiline string values must be triple-quoted:
[song] lyrics = """ # (or triple single-quotes: '''value''') No stop signs Speed limit Nobody's gonna slow me down """
- List Values
List values are comma-separated:
animals = dusty, fido, cujo
- Boolean Values
Booleans are capitalized:
ice cream is good = True # or False
- Sections and Sub-sections
Settings have a level-dependent number of square brackets:
[section] [[sub-section]] [[[sub-sub-section]]]
- Indentation
It is advisable to indent sections and subsections, for clarity. However, Cylc ignores indentation, so this:
[section] a = A [[sub-section]] b = B b = C # WARNING: this is still in sub-section!
is equivalent to this:
[section] a = A [[sub-section]] b = C
- Duplicate Sections and Items
Duplicate sections get merged into one. Duplicate settings overwrite previously defined values. So this:
[animals] cat = fluffy [animals] dog = fido cat = dusty
is equivalent to this:
[animals] cat = dusty dog = fido
The only exception to this rule is graph strings, which get merged. So these graph strings:
R1 = "foo => bar" R1 = "foo => baz"
merge to this:
R1 = "foo => bar & baz"
- Continuation lines
If necessary, you can continue on the next line after a backslash character:
verse = "the quick \ brown fox"
However, backslash line continuation is fragile (trailing invisible whitespace breaks it). Long graph strings strings should be split on graph symbols instead:
R1 = """ (foo & bar ) | baz => qux """ # Equivalent to: R1 = """ (foo & bar ) | baz => qux """
- Include-files
flow.cylc
fragments can be included verbatim with the%include
directive. Include-files can be included multiple times, and even nested. Include-file paths should relative to theflow.cylc
location:%include "inc/site-a.cylc"
Jinja2’s template inclusion mechanism can be used with Cylc too.
Shorthand
We often use a compact single-line notation to refer to nested config items:
[section]
An entire section.
[section]setting
A setting within a section.
[section]setting=value
The value of a setting within a section.
[section][sub-section]another-setting
A setting within a sub-section.
In the file, however, section headings need additional brackets at each level.
# This:
# [runtime][task-a][environment]FOO = foo
# Means:
[runtime]
[[task-a]]
[[[environment]]]
FOO = foo