Config Files, YAML and TOML
Level 3 · Config and docs files
What a config file is for, and the two formats most of them use. How YAML uses indents, how TOML uses headings, and the traps in each.
Course contentsLesson 5 of 11
Level 1 · Files and formats
Level 2 · Data formats
Level 3 · Config and docs files
Level 4 · Characters and escapes
Level 5 · IDs, dates and patterns
After this lesson you can
- Say what a config file does
- Read a YAML file and a TOML file
- Avoid the tab and NO traps
13 mincovers 3 glossary entries
Worth reading first: Serialization and Protobuf
How YAML and TOML hold a program's settings
A config file holds the settings a program reads when it starts, so you can change how it acts without changing its code. Most are written in YAML or TOML. YAML groups settings with indents and spaces. TOML groups them under headings in square brackets. TOML reached version 1.0 in January 2021.
A project often has several config files, one for each tool. The linter has one, the test tool has one, and so does the app itself. Each file is plain text, so it goes into Git and changes with the code.
YAML was built to be easy to read. A name, a colon and a value make one setting. Lines indented under a name belong to it, and a dash starts each item in a list. It allows comments after a # sign, which JSON does not.
The spaces in YAML carry meaning, and that is its main trap. A line indented one space too far joins the wrong group. Tabs are not allowed at all, and a single tab makes the file fail to load. Set your editor to put in spaces.
YAML also guesses types, and the guesses can be wrong. Older YAML readers, built on version 1.1, read a bare NO as false. So a country code for Norway turns into false. They also read 1.10 as the number 1.1. Put quotes around any value that must stay text.
TOML is stricter, so it has fewer surprises. Each line sets one value, like name = "shop". Text must be in quotes, so it is never guessed. Settings sit under a heading in square brackets. Rust projects use it in Cargo.toml, and Python projects in pyproject.toml.
The common mistake in TOML is leaving the quotes off text. The line name = shop is an error, not a setting. The fix is always the same: name = "shop". Many editors check both formats as you type.
server:
name: shop
country: NO
version: 1.10[server]
name = "shop"
country = "NO"
version = "1.10"Worked example
Lucy's country list loses Norway
Lucy's shop reads its list of 12 shipping countries from a YAML file. Orders to Norway keep failing, while the other 11 work.
She finds the reader turned NO into false. She puts quotes around "NO", and Norway orders go through.
The words for this lesson3
Check yourself
Why does my YAML file fail to load after I indent a line?
Finished this lesson?
Marking it complete also marks its 3 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.