This will be a kind of review of YAML, mostly to spark interest in this unique file format.

When I first heard about YAML, a superset of JSON, I thought it looked quite ugly and cumbersome. That isn't to say JSON, or XML don't look ugly, but it had lots of funky characters and no clear separators.

Today, I used it for the first time in my game to define the available weapons and their attributes. For this task, it was pleasant, concise, readable, and easy to work with.

Here's a piece-by-piece sample:

# Weapons! Defined in YAML! What a crazy language ... very handy, though, and easy to type

A comment!

- &hornet_missile_launcher
  name:         Hornet Missile Launcher
  type:         missile
  cost:         10000
  slots:        1
  reloadtime:   4
  lifespan:     4
  image:        images/missile1
  size:         1.5
  damage:       [0.3, 1.5]
  maxturn:      0.04
  velocity:     40

This is the definition of a single weapon. - marks the beginning of a new array element. &hornet_missile_launcher is an "anchor", and allows me to reference this weapon later in the file. The rest is an associative array definition. You'll notice the lack of quotes, which aren't needed unless you need to disambiguate. damage is an array of numbers, [0.3, 1.5]

Now for the really cool stuff!

- <<: *hornet_missile_launcher
  name:         Hornet Missile Launcher MkII
  cost:         40000
  reloadtime:   2
  damage:       [0.6, 3.0]

A new weapon, based on a previous weapon. <<: *hornet_missile_launcher copies all the key:data pairs from the hornet_missile_launcher, allowing me to "extend" it (in some sense). Very neat!

The rest of my configuration is just like that, with some parent definitions, and weapons that extend those and tweak little things here and there.

Things I Liked

• Quotes and other cumbersome syntax is not needed, except to disambiguate. I am a big fan of this mentality. It's less typing, more concise, and quite readable.

• Pick your poison. You can write full-on YAML, or degrade to just writing JSON, since JSON is a subset of YAML)

• Nice syntax highlighting in editors. At least in SciTE, YAML was enhanced by the syntax highlighting.

Things I Didn't Like

• Some of the syntax is still ugly. Anchors and "data merge" syntax ( <<: *anchor_name ) is fugly. I couldn't indent the weapon data because it was part of an array element (I guess). And there's plenty of other oddities I didn't use here.

• No built-in parser in Python (my game's scripting language)

• It's semi-whitespace dependent (for figuring out hierarchies). I am personally not excited about whitespace dependent syntax

• PyYAML is broken?

PyYAML is Broken?
To elaborate, it throws an error when you use tabs to separate things. Not only is that silly, but from what I could find online the YAML spec was updated to make clear that tabs are indeed considered valid whitespace. I patched the code very quickly, so it is not a problem for my project, but I hope they fix it for everyone else.

That's it! So, go ahead, give YAML a try!

It looks a lot nicer than the equivalent XML would, that's for sure.

I'm using YAML both in my C (libyaml, a bit verbose API but easy to wrap) and Python (just "import yaml", whatever that uses) code and like it. So far I'm not using tags/anchors or types besides the 3 base types so I avoided all the syntax oddities so far. Just nested mappings and sequences using plain/implicit styles.

I guess if I don't change to Allegro config files I could start using more of YAML's features. In the C case, one advantage of config files is that C has no standard mapping type but you need something to put the libyaml data into. With config files you get the mapping built in.

Well, most of us Python people never use tabs because the style guide advices against using them

Back when I was reviewing YAML I couldn't find an easy to use C library for it, so I didn't use it. Ended up making my own format.

Looks pretty handy for all those gameplay constants. I generally manage them in Excel and generate C source from a formula column , but this is more direct: it's tweakable without recompiling, even the end-user can "mod" the game somehow.
And this text format is friendly enough for source control tools.