Using TOML

This chapter is just a quick introduction to TOML language. Their own website explains it really well, and I advise you spend some time reading it.

A config file format for humans.

TOML aims to be a minimal configuration file format that’s easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.

Source: TOML: Tom’s Obvious Minimal Language

The quotation above is how they describe their own language, it makes more sense if you’re a software developer. The important part is a minimal configuration file format that’s easy to read, meaning that TOML is designed to be pleasant to the eyes of both humans and software.

In their website, they have a section called A Quick Tour of TOML that goes over every aspect of the language, go read that after finishing this chapter.

If you ever edited a .INI file on Windows, then you’ll feel just at home. For the purposes of Little Webby Press, a TOML file is divided into sections. Each section has a name that is always a single word and lowercase. So the section called metadata is written in TOML as:

[[ metadata ]]

All content below a section declaration belongs to that section. Once a new section starts, the content below that section will belong to the new section. For example, consider:

[[ opinions ]]
chocolate = "I like it, but don't eat often"
grapes = "Goes well with cheese, I really like them"

[[ doubts ]]
cat = "My cat is from Brazil, does he meows in Portuguese?"

There are two sections in the sample above. One called opinions has two fields in it: chocolate and grapes. The content of those fields is my own opinion regarding chocolate and grapes. The second section, doubts, holds a single field cat with my own doubts about which language my cat meows in.

TOML is analogous to writing a paper form. You have sections, fields, and the content of those fields.

A TOML file is always a plain text file. You should not use applications such as Word to write them, you should use a plain text editor such as Sublime Text, Visual Studio Code, or ATOM. If you don’t want to install one of those editors, you can use whatever plain text editor comes with your operating system. On a Mac that is TextEdit, on Windows it is Notepad, and on Linux depends on your distro but you should have a couple installed.

In our video tutorials I talk a bit more about editors and why I think you should install a good one.