The special keys (namely merging) in the spec

To the YAML spec writers,

As the spec's just about done, I'd like to interject with one more
question—on a somewhat strange and somewhat undocumented feature of
the language, "special keys" (of which currently exist in the type
repository "=" and "<<"). I could find no name for them on the
Internet other than in the old reference card
(http://www.yaml.org/refcard.html), so I'll call them as such too.

I would like a small section in the spec devoted to special keys—in
particular, the merge key.

I think that regardless of whatever specific special keys exist (a
question that has rightly been delegated to the type repository),
special keys—such as the merge key—often cannot be defined as simple
tags. They necessitate what I believe to be an *extra step* in the
Loading of YAML streams (probably in the Construction stage).

Consider the following document:
---
- &CENTER { x: 1 }
- # Merge one map
  << : *CENTER
  r: 10
...

During Parsing and Composing, the nodes' tags will be evaluated as the
following using the standard types from the repository:
---
!!seq [
  !!map {
    !!str "x": !!int "1"
  },
  !!map {
    !!merge "<<": !!map { !!str "x": !!int "1" },
    !!str "r": !!int "10"
  }
]
...

Now I ask: during Construction, how does the magic happen and the
CENTER map gets merged? I see two things may happen:
- The onus is on the constructor of the mapping object containing the
merge key. The mapping
  must detect the merge key and then incorporate its contents into itself.
- The onus is on the YAML loader, right before Construction. The
loader searches for special
  keys and, upon finding the merge key, edits the mapping node
containing the key, merging
  the node with whatever value corresponds to the merge key.

The first option is a bad idea, because every mapping type must then
be able, independently, to support the merge key in case it gets fed a
mapping that contains one.

The second idea is better because it definitely preserves the
definition of the merge key, relieving the burden of it from the users
of the YAML loader—the implementers of the type constructors.
Furthermore, it is much more extendible—should another special key be
added to the YAML type repository, it can be implemented only once.

The second idea, though, also requires an extra step in the Loading of
a stream, right before Construction. I think that the behavior of the
merge key entails a note in the spec's Chapter 3 about processing
special keys. This would make clear and explicit something that
confused me for a long time, as well as shedding light on a
little-documented feature of YAML.

Sorry to have written so much about such a boring topic. :)

Sincerely,
Joshua Choi

------------------------------------------------------------------------------
OpenSolaris 2009.06 is a cutting edge operating system for enterprises 
looking to deploy the next generation of Solaris that includes the latest 
innovations from Sun and the OpenSource community. Download a copy and 
enjoy capabilities such as Networking, Storage and Virtualization. 
Go to: http://p.sf.net/sfu/opensolaris-get