Yaml Syntax

This page provides a basic overview of correct YAML syntax, which is how Bane Of Wargs plugins or vanilla game data are expressed.

We use YAML because it is easier for humans to read and write than other common data formats like XML or JSON. Further, there are libraries available in most programming languages for working with YAML.

Yaml Basics

Each item in the list is a list of key/value pairs, commonly called a “hash” or a “dictionary”. So, we need to know how to write lists and dictionaries in YAML.

There’s another small quirk to YAML. All YAML files (regardless of their association with Bane Of Wargs or not) can optionally begin with --- and end with .... This is part of the YAML format and indicates the start and end of a document.

All members of a list are lines beginning at the same indentation level starting with a "- " (a dash and a space):

---
# A list of tasty fruits
- Apple
- Orange
- Strawberry
- Mango
...

A dictionary is represented in a simple key: value form (the colon must be followed by a space):

# An employee record
martin:
  name: Martin D'vloper
  job: Developer
  skill: Elite

More complicated data structures are possible, such as lists of dictionaries, dictionaries whose values are lists or a mix of both:

# Employee records
- martin:
    name: Martin D'vloper
    job: Developer
    skills:
    - python
    - perl
    - pascal
- tabitha:
    name: Tabitha Bitumen
    job: Developer
    skills:
    - lisp
    - fortran
    - erlang

As yaml is a superscript of json, you can actually embed json in yaml, to save some space:

---
martin: {"name": "Martin D'vloper", "job": Developer, "skill": Elite}
fruits: ['Apple', 'Orange', 'Strawberry', 'Mango']

You can also specify a boolean value (true/false) in several forms:

used key: true
showed dialog: yes
closed game: false
finished mission: no

Use lowercase ‘true’ or ‘false’ for boolean values in dictionaries if you want to be compatible with default yamllint options; even if yes and no can still be used.

Values can span multiple lines using | or >. Spanning multiple lines using a “Literal Block Scalar” | will include the newlines and any trailing spaces. Using a “Folded Block Scalar” > will fold newlines to spaces; it is used to make what would otherwise be a very long line easier to read and edit. In either case the indentation will be ignored. Examples are:

include newlines: |
            exactly as you see
            will appear these three
            lines of poetry

fold newlines: >
            this is really a
            single line of text
            despite appearances

While in the above > example all newlines are folded into spaces, there are two ways to enforce a newline to be kept:

fold_some_newlines: >
    a
    b

    c
    d
      e
    f

Alternatively, it can be enforced by including newline \n characters:

fold_same_newlines: "a b\nc d\n  e\nf\n"

Note that the the “Literal Block Scalar” | has a variant, which prevent a new line at the ending line:

include newlines: |-
            Some lines of various
            information that
            your probably don't care about

include newlines real: "Some lines of various\ninformation that\nyou probably don't care about"
instead of: "Some lines of various\ninformation that\nyou probably don't care about\n"

Let’s combine what we learned so far in an arbitrary YAML example. This really has nothing to do with Bane Of Wargs, but will give you a feel for the format:

---
# <- yaml supports comments, json does not

json:
- rigid
- better for data interchange
yaml:
- slim and flexible
- better for configuration
object:
  key: value
  array:
  - null value: null
  - another null value:
  - boolean: true
  - integer: 1
  - alias: aliases are like variables
  - alias: aliases are like variables
paragraph: |
  Blank lines denote
  paragraph breaks
content: |-
  Or we
  can auto
  convert line breaks
  to save space
alias:
  bar: baz
alias reuse:
  bar: baz 

That’s all you really need to know about YAML to start reading Bane Of Wargs wiki pages.