[Yaml-core] Special Keys revisited

[Clark C . E. <cc...@cl...>]

Brian Ingerson wrote:
| > | | > - Change the comment special key to ';.*'.
| > | | 
| > | | -3
| > 
| > Yes.  I really don't like this one either.  I prefer (#comment)
| > actually.  Oren made the note that it doesn't allow things to be
| > easily commented-out.  After a bit more reflection, I don't think
| > that commenting things out via the special key mechanism needs
| > to be a simple operation.  Its a rather "rare" feature, and 
| > (#comment) is very clean, as things between parenthesis are
| > rather simple.
| 
| Good point. But,...
| 
| Before we go down this road any further, I'd like a quick explanation on
| how special comments are supposed to work. I've kind of ignored these as
| one of Clark's special needs, but now that there's an issue, I'd like to
| readdress why we need them at all.
| 
| Specifically:
|   - How are these represented in the various info models?
|   - What would they look like in the serialization?
|   - What _kinds_ of nodes do they affect?
|   - How many of them are allowed per node?
|   - Are the order of comments preserved?
| 
| While you're at it, you should probably address the similar issues for the
| default key '='.

Ok.  There are two "special" keys currently, and we may add a few
more in the short term, especially after we start developing YATL.
The purpose of the special key mechanism is to provide for a shared
expression of common idioms, like comments, etc.  The mechanism is 
a thin layer on top of YAML itself.

   - They are not represented in the various information models
   - In the serialization they look just like any map key
   - They can affect any map object
   - Being keys, only one is allowed per node
   - Being keys, order is not preserved

There are two of them thus far:

   migration: >

     The migration operator (=) helps solve a "migration problem"
     when a given node must be converted from a list or scalar
     into a mapping.   This gives software expecting a list or
     scalar a place to look, that is, the content of the equals.

     A pull based API could directly support such a notion, where
     when you ask for a node's value (expecting it to be a scalar)
     it returns the scalar value if it is a scalar, otherwise, if
     the node is a mapping, it would look for a (=) key to find
     an apporpriate scalar value.

     The existence of this key doesn't automagically enable apps
     to have forwad-migration ability; but it sets out a clear 
     path so that this sort of commonly needed functionality is
     clearly possible, and possible across a wide range of tools.

  comment: >
 
     Many times there are application level comments for a node
     that wish to be round-tripped.  This provides a idiom for
     an appliction to use so that various tools can be aware of
     the comment.   More than one comment is allowed by varying
     the comment key slighly "//" vs "//more"
  
     This idiom is useful for commenting out specific items
     so that an application doesn't use them, but general YAML
     processes are still required to round-trip the comments.
     As another example, a YATL optimizer could add a bunch of
     comment nodes containing various optimization hints.
  
There are a few other common "idioms" which we will probably want
to add in the future:

  inheritance: >

     This is a mechansim to say that a given mapping has all of the
     keys from another mapping.   Very useful for data specializing.

  primary-key: >

     I have an "id" field which is a unique identifier across the
     entire document.  Since this is a very common pattern, many
     processes could take advantage of it.  Thus, perhaps it is worthy
     of special-key status?

That said, our first two special keys use "special" syntax:

---
  //:  Comment
   =:  &0 Migration value
  one: Some data
  two: *0

When we originally did special keys, we didn't yet have the parenthesis
mechanism.  So, we may want to re-factor and migrate the items above
to use the parenthesis...

---
  (#): Comment
  (=): &0 Migration value
  one: Some data
  two: *0
 
I think the bare ones are nicer looking, but I bet they could also
throw a newbie for a loop.   However, I could see a tutorial saying
that stuff in parenthesis are things that are implicitly typed.  In 
this way, we get some consistency, and it could be more useful to add
stuff like (@): *001  for inheritance, or (id): 293 for a unique 
identifier.  The parenthesis would be a clear visual cue to the 
reader that it's something "special", just like (true), (false), etc.

Therefore, I guess I'm suggesting that we keep our special keys
(and perhaps even add inheritance) but that we move to using 
parenthesized forms (as ugly as it looks) so that we are clearly
marking special things as special.

Best,

Clark 
     
   forward-compatible: