YAML Guide

Table of contents:

• Introduction
• Nodes
  • Node keys
  • Node values
    • Scalar values
    • Lists
    • Objects

• JSON format
• Anchors

Introduction:

• In MagicSpells data YAML files are those with the file extension .yml.
• You can write comments like this:

#comment 1
is_true: true #comment 2

• Indentation must be done with spaces, not TAB spaces.

map:
    validKey: true
	validKey: false

Nodes:

A node is a key-value pair.

key: value

Node Keys:

In general, YAML keys can include spaces, but in:

• MagicSpells configuration they follow dash case.
• EffectLib configuration follows any case.

Node Values:

There are two major types of values, Scalar and Collection (lists & objects).

Scalar Values:

• Boolean can either be true or false.
• Numeric can be integer or floating-point (decimal).
• String refers to text.
  • If strings include special characters, they must be enclosed in quotes, if not they may be quote-less (plain). One example of special characters is the new line \n.

plain-string: some value
string1: "one\n1"
string2: 'two\n2'
string3: 'three "3"'
string4: "four '4'"

• • If you need to put the same type of quotes inside quotes, you can use the character \ to escape the inner quotes, defining a valid string. Additional \ can be added for each level of depth.

string: "1 \"2\" '3' \"\\"4\\"\""
# Prints: 1 "2" '3' ""4"" 

• You can also write multi-line strings.
• • You can also write a multi-line string (for readability) in the config which is parsed into a folded, single-line string.

folded: >
    hello
    world
# Parses into: "hello world\n"
next-node: value

• • You can also write Blocks which keep the multi-line format by using the | character instead of >.

block: |
    hello
    world
# Parses into: "hello\nworld\n"
next-node: value

• • You can add indentation to the finally parsed string in one place if you'd like, after the special character.

string: |2
    hello
    world
# Parses into: "  hello\n  world\n"

• • You'll notice these multi-line formats put the extra newline character at the end. You can put the - character after the special character (and indentation if that was included) to remove it. Otherwise, it's kept as if you put +.

folded: >-
    hello
    world
# Parses into: "hello\nworld"
block: |2-
    hello
    world
# Parses into: "  hello\n  world"

Lists:

• Ordered scalar list, also referred to as array or sequence. It can contain one or more values, scalar, list, or objects.
• All items of a list must be indented with the same amount of spaces, 0 or more. The practice is to use 4 spaces.
• Here are some examples of valid lists:

list:
    - "single value"
    - 2
listOfLists:
    -
        - one
        - two
    -
        - three
        - four

Objects:

• Unordered list, which is also known as a map or configuration section.
• All nodes on an object must be indented with the same amount of spaces, at least 1 or more. The practice is to use 4.

map:
    key: value
    anotherMap:
        key: value

JSON format:

• You can represent all data in YAML with JSON. Below is an example of lists and objects, and how they can be compacted.
• Note that compact data is hard to read, so only compact things if doing so makes your configuration more readable. (One example is if you have a list with a single item - instead of listing that item on a separate line, you could compact the spell list in one line.)

listNormal:
    - item1
    - item2
listCompact: [item1, item2]

mapNormal:
   key1: value
   key2: value
mapCompact: {key1: value, key2: value}

You can also do the following:

# Here's a map of lists:
map:
    list1:
        - item1
    list2: [item1]
# Here's a list of maps.
list:
    - key1: one
      key2: two
    - {key1: three, key2: four}

Anchors:

• If you have a configuration section that is duplicated elsewhere in the file, you can use anchors to anchor one, and reference it below instead of configuring a duplicate map.

map1: &myMap
    key1: 42
    key2: 42
# map2 will now have the same nodes as map1.
map2: *myMap
# This is another way to reference anchors.
map3:
    <<: *myMap
# With that alternative way you can add extra nodes.
map4:
    a: 1
    <<: *myMap
    b: 2
# Or edit some of the referenced values.
map5:
    <<: *myMap
    key2: 0

• There's an alternative way to make anchors that only take select nodes.

map1:
    # Indented nodes are collected.
    <<: &myMap
        key1: 42
    key2: 42

# Referencing the above like this:
map2: *myMap
# Returns this:
map2:
    key1: 42