YAML TERMINOLOGY
YAML is a full featured data serialization language, and thus has its own terminology.
It is important to remember that although YAML is heavily influenced by Perl and Python, it is a language in its own right, not merely just a representation of Perl structures.
YAML has three constructs that are conspicuously similar to Perl’s hash, array, and scalar. They are called mapping, sequence, and string respectively. By default, they do what you would expect. But each instance may have an explicit or implicit tag (type) that makes it behave differently. In this manner, YAML can be extended to represent Perl’s Glob or Python’s tuple, or Ruby’s Bigint.
stream
A YAML stream is the full sequence of Unicode characters that a YAML
parser would read or a YAML emitter would write. A stream may contain
one or more YAML documents separated by YAML headers.
---
a: mapping
foo: bar
---
- a
- sequence
document
A YAML document is an independent data structure representation within a stream. It is a top level node. Each document in a YAML stream must begin with a YAML header line. Actually the header is optional on the first document.
---
This: top level mapping
is:
- a
- YAML
- document
header
A YAML header is a line that begins a YAML document. It consists of three dashes, possibly followed by more info. Another purpose of the header line is that it serves as a place to put top level tag and anchor information.
--- !recursive-sequence &001
- * 001
- * 001
node
A YAML node is the representation of a particular data structure. Nodes may contain other nodes. (In Perl terms, nodes are like scalars. Strings, arrayrefs and hashrefs. But this refers to the serialized format, not the in- memory structure.)
tag
This is similar to a type. It indicates how a particular YAML node serialization should be transferred into or out of memory. For instance a Foo::Bar object would use the tag 'perl/Foo::Bar':
- !perl/Foo::Bar
foo: 42
bar: stool
collection
A collection is the generic term for a YAML data grouping. YAML has two types of collections: mappings and sequences. (Similar to hashes and arrays)
mapping
A mapping is a YAML collection defined by unordered key/value pairs with unique keys. By default YAML mappings are loaded into Perl hashes.
a mapping:
foo: bar
two: times two is 4
sequence
A sequence is a YAML collection defined by an ordered list of elements. By default YAML sequences are loaded into Perl arrays.
a sequence:
- one bourbon
- one scotch
- one beer
scalar
A scalar is a YAML node that is a single value. By default YAML scalars are loaded into Perl scalars.
a scalar key: a scalar value
YAML has many styles for representing scalars. This is important because varying data will have varying formatting requirements to retain the optimum human readability.
plain scalar
A plain scalar is unquoted. All plain scalars are automatic candidates for "implicit tagging". This means that their tag may be determined automatically by examination. The typical uses for this are plain alpha strings, integers, real numbers, dates, times and currency.
- a plain string
- -42
- 3.1415
- 12:34
- 123 this is an error
single quoted scalar
This is similar to Perl's use of single quotes. It means no escaping except for single quotes which are escaped by using two adjacent single quotes.
- 'When I say ''\n'' I mean "backslash en"'
double quoted scalar
This is similar to Perl's use of double quotes. Character escaping can be used.
- "This scalar\nhas two lines, and a bell -->\a"
folded scalar
This is a multiline scalar which begins on the next line. It is indicated by a single right angle bracket. It is unescaped like the single quoted scalar. Line folding is also performed.
- >
This is a multiline scalar which begins on
the next line. It is indicated by a single
carat. It is unescaped like the single
quoted scalar. Line folding is also
performed.
block scalar
This final multiline form is akin to Perl's here-document except that (as in all YAML data) scope is indicated by indentation. Therefore, no ending marker is required. The data is verbatim. No line folding.
- |
QTY DESC PRICE TOTAL
--- ---- ----- -----
1 Foo Fighters $19.95 $19.95
2 Bar Belles $29.95 $59.90
parser
A YAML processor has four stages: parse, load, dump, emit.
A parser parses a YAML stream. YAML.pm's Load() function contains a parser.
loader
The other half of the Load() function is a loader. This takes the information from the parser and loads it into a Perl data structure.
dumper
The Dump() function consists of a dumper and an emitter. The dumper walks through each Perl data structure and gives info to the emitter.
emitter
The emitter takes info from the dumper and turns it into a YAML stream.
NOTE: In YAML.pm the parserloader and the dumperemitter code are currently very closely tied together. In the future they may be broken into separate stages.
For more information please refer to the immensely helpful YAML specification available at http://www.yaml.org/spec/.