As discussed in the Document Mechanization and #DDF Entry Format tutorials, the FSW document production scripts make very heavy use of YAML, a data-serialization format which provides direct encodings for Perl's scalars, hashes, and lists.

YAML has a very rich syntax, but the FSW scripts use only a small subset of it. On the other hand, certain local idioms (e.g., splittable text strings) are used to extend this subset. This tutorial describes the local style of YAML use, concentrating on the constructs and idioms which are found in FSW YAML files.

YAML Basics

• Comment lines

  Comment lines begin with zero or more spaces, followed by a pound sign (#).

• Indentation, etc.

  YAML (like Python) uses indentation to indicate structure. If an entry is indented further than a preceding entry, it is (in general) part of that entry. Although tabs are allowed in certain situations (e.g., in quoted strings and comments), they may not be used for indentation.

• Quoted strings, etc.

  In double-quoted strings ("foo\nbar"), certain escape codes are expanded. In single-quoted strings ('foo'), no escape codes are expanded.

  Note: FSW YAML files seldom use escape codes. In general, double-quoted strings are only used when the content includes a single quote.

  The "|" and ">" operators each indicate the beginning of a multi-line string. The former preserves indentation and newlines; the latter does not.

• Hash entries

  A hash entry is indicated by a name (or quoted string), followed by a colon ('Key1:').

• List entries

  A list entry is indicated by a dash (-).

• Aliases

  YAML aliases provide ways to capture and re-use defined values. In the example below, &foo captures the value abc. The value is re-used (via *foo) in the following line.

This example demonstrates most of the constructs which appear in FSW YAML files:

    # This YAML snippet encodes a 2-element hash.

    # Key1 is a hash entry, containing a 6-element list.

    Key1:
      -    1
      -    &foo abc
      -    *foo
      -    'some text'
      -    >
        a bit of
        line-wrapped text
      -    |
        A B C D E F G
        1 2 3 4 5 6 7

    # Key2 is another hash entry, containing a 2-element hash.

    Key2:
      foo:    123
      bar:    456
      '1.2':  789
    

Assuming that the above snippet has been loaded into memory and attached to the hashref $r, the following should be true:

• $r->{Key1}[0] contains '1'.

• $r->{Key1}[1] and $r->{Key1}[2] contain 'abc'.

• $r->{Key1}[3] contains 'some text'.

• $r->{Key1}[4] contains 'a bit of line-wrapped text'.

• $r->{Key1}[5] contains "A B C D E F G\n1 2 3 4 5 6 7".

• $r->{Key2}{foo}, $r->{Key2}{bar}, and $r->{Key2}{'1.2'} contain, respectively, '123', '456', and '789'.

YAML Standardization

At the time that work began on the FSW document production scripts, the YAML specification was very much in flux. Even in early 2005, some fine points are still being hammered out. Efforts are under way to develop conforming emitters and parsers, but it could be months until they are reliably available.

So, the version of YAML used in FSW YAML files follows a de facto specification: whatever is supported by Version 0.35 of Brian Ingerson's pure-Perl YAML.pm module. This has precluded the use of certain constructs, but the eventual standards-based parsers should have little trouble with FSW YAML usage. (If they do, YAML.pm can still be used. :-)

Local YAML Idioms

• Encoded lists

  Some lists are encoded as strings, delimited by spaces, commas, or other characters (e.g., "A B C", "D,E,F", "G, H, I"). YAML returns these values as strings, so the receiving script must split() them on the appropriate delimiter, if lists are desired.

• Brace expansion

  Following csh(1) practice, some whitespace-delimited lists use a combination of braces and commas to encode combinations. Thus, "{A,B}1{D,E} F" might expand to "A1D A1E B1D B1E F".

• Oddball keys

  Any (quoted) string can be used as a key, so some rather unusual keys may show up. In e_etc/rtt_fsw.yml, for example, section numbers (e.g., '3.2.2') are used as keys.