YAML Format

From Flashpoint Datahub
Jump to navigation Jump to search

Basic Principles

YAML is a very simple, human-readable text format that can be used to store data.

In YAML, data is stored as a map containing keys and values associated to those keys. This map is in no particular order, so you may reorder it at will.

Title: Alien Hominid
Series: 
Developer: The Behemoth
Publisher:
Play Mode: Single Player 
Status: Playable
Extreme: No
Genre: Shooter
Source: Newgrounds.com
Launch Command: http://uploads.ungrounded.net/59000/59593_alien_booya202c.swf
Notes: 
Author Notes: Thanks for your work!

Special Characters

When using special characters, it is sometimes necessary to enclose the values in quotes or double quotes. Whichever you use is up to you.

To simplify things, I suggest quoting all strings that contain special characters.

Invalid:

Developer: @bluemaxima
           ^

Valid:

Developer: "@bluemaxima"

or

Developer: '@bluemaxima'

To ensure that your YAML is valid, you can copy and paste it to a site like yamllint.com, it will tell you if its valid or if it's not, point you to where the issue is.

Nested Keys

Keys may also be inside other keys, this is denoted by the use of indentation. Do not use tabs for indentation. Always use spaces.

The amount of spaces doesn't matter as long as all sub-keys use the same amount of spaces, though the general convention is to use two spaces.

Additional Applications:
  Extras: drop3
  Message: This message will pop up before the game runs.
  Play Hacked Version:
    Application Path: Games\flashplayer.exe
    Launch Command: http://www.irregulargames.com/drop3/drop3-hacked.swf

Multiline Values

Multiline values can be introduced by using a pipe "|" character. Content then starts in the next line and must be indented.

These values do not need to be enclosed by quotes, regardless of any special characters.

Curation Notes: |
  This is a new example meta.txt.
  What do you think?

Comments

YAML files can include comments, these may appear anywhere in the file.

Title: Flashpoint
# remember to quote values with special characters
Developer: "@bluemaxima" # like this

This means that if you want to include a number sign inside a value you must quote it.

Title: "#notacomment"

Lists

A key can have multiple values, these are expressed by a dash "-" character in individual lines.

Languages:
- en
- es
- fr
- it

Alternatively, you may also express them in a single line. To do so, enclose them in square brackets and separate them using commas.

Languages: [en, es, fr, it]

Editor Choice

It's not recommended to use a WYSIWYG editor like Word to edit YAML files.

Instead, use something like Notepad++. You can also modify its settings so that pressing tab uses spaces like so.


Advanced Rules

Quotes inside values

In values enclosed by quotes "", you may include quotes as part of the value itself by prepending them by a backslash "\" character.

Developer: "John \"Doe\" Douglas"

In values enclosed by single quotes '', you may include single quotes as part of the value itself by doubling them up.

Developer: 'John ''Doe'' Douglas'

Cool trick

You can also use the following to avoid having to escape values.

Curation Notes: >
  "Hello World" is a typical phrase used by programmers used in their first "program"

It's very similar to the multiline value syntax but using a greater-than symbol instead of a pipe.

This syntax is called a "folded block", this is because it allows you to cosmetically break up a value into multiple lines while keeping it in a single line once parsed.

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