YAML Tutorial

All Utterly Voice settings files use a format known as YAML. This is a common text file format used by many applications to organize settings data. You only need to know the basics of this format, which this page teaches you. If you are already familiar with YAML, you can skip this page.

Document Start

YAML files begin with the document start marker ---. For example, see the first line of this simple file:

Key-Value Pairs

The YAML format is fundamentally a collection of many key-value pairs. The keys are the names of specific settings, and the values are the values for those settings.

A key and value are separated by :, with the key on the left and the value on the right. For example, the following file has a key called "age" with a value of 22:

Each value has a specific type, which can be one of the following:

• Number
• Boolean (true or false)
• String (text)
• Map Collection (related keys and values)
• List Collection (list of values)

The sections below describe each of these types.

Number Values

Some settings have a value that is a number. For example:

Boolean Values

Some settings have a value that is a boolean value that is either true or false. For example:

String Values

A string value is used to provide text as a value. There are several ways to represent strings with YAML, but this documentation explains three methods that are most useful in Utterly Voice settings.

• For most settings, you should use double quotes " to wrap a string value.
• In some scenarios described in the next section, you should use single quotes ' to wrap a string value.
• For long strings, you can use >-, then a newline, then one or more lines of indented text. This is called block style for a string.

The following example shows the three ways to provide a string value:

String Escape Sequences

If a string value needs to contain a double quote ", a single quote ', a backslash character \, a newline character, or a tab character, you need to consider how escape sequences work.

Consider this string value:

This string will not work as expected. When the first open quote is encountered by the application reading the file, the application will look for the next open quote to decide where the string ends. This happens just before Tarzan. A similar problem happens when you include a single quote in a string that is wrapped in single quotes.

To fix this problem, you use an escape sequence. Escape Sequences are special sequences of two characters that get translated as the character you actually want when the application reads the data. These escape sequences are used to solve the quoting issues described above and to insert special characters.

Most escape sequences only apply to double quoted strings. Single quoted strings only have one sequence. Block style strings do not support any escape sequences. The following table describes the escape sequences:

From the table above, notice that only one escape sequence is relevant for single quoted strings. This is the only sequence recognized by this type of string. This makes single quoted strings useful when you want to use the backslash \ character in the string, because you do not need an escape sequence for it.

For block style strings that use >-, no escape sequences are supported. This means that you cannot insert a newline character in the string. If you need to do this, just use a double quoted string.

The following example shows how to use escape sequences in strings:

YAML supports many ways to provide strings and escape sequences. The options described in this page should be everything you need for Utterly Voice settings. If you would like to try other options, see this post for an excellent overview of all of the options.

Map Collections

A map collection is a collection of related keys and values. When a setting has a value that is a map collection, the map collection value starts on the next line and is indented. For example, see the following person map collection that has name and age keys:

List Collections

A list collection is a list of values. When a setting has a value that is a list collection, the list collection values start on the next line and are indented. Each list collection value starts with - . For example, see the following animals list collection:

Collection Hierarchy

Each value in a list can be another list or a map. Each value in a map can be another map or a list. This creates a hierarchy of collections. There is no limit to how deep the hierarchy can be. For example, the following people list collection is a list of maps. Each map has name and age keys. Notice how - is used to start each item in the list.

The following person map collection has name and friends keys. The friends key has a value that is a list.

Indentation

Indentation in a YAML file is important. If you look at the collection examples above, all values within a collection are indented two spaces to the right of the collection or list value start (-) they belong to. This indentation helps to define the hierarchy of collections. As a hierarchy grows deeper, so does the indentation.

Comments

You can include comments in the file using #. Everything after # on a line in the file is a comment. Comments are not processed by the application; they only help to explain the data in the file for anyone who is reading it. For example, see the two comments in this file:

YAML validation

If you edit a settings file, and Utterly Voice displays an error about the file at startup, you probably entered invalid YAML. The easiest way to find the problem in your file, is to use an online YAML validation tool. These tools will show you exactly where the problem is. There are many tools that perform this. One recommended tool is YAML Lint.