YAML Ain't Markup Language

"Clark C . Evans" wrote:
> 
> Ok.  Oren seems to think that we should drop
> the special class notation and use a more
> general coloring mechanism.  I tend to agree,
> so let's work this out.

I think something like Oren's coloring scheme will definitely be needed.
This is the encoding I would use for special "YAML" objects in Perl.
(Objects that inherit from the YAML class) With these objects you could
override emitter methods like sort(), for instance. Anyway, I think the
color scheme is probably a good encoding, and a necessary functionality.

*But*, I also think the implications of it will be too restrictive for
Perl. Encoding every little Perl object as a full-fledged YAML object
will not fly. Using methods to get and set attributes would be an utter
nightmare in the general case. And besides Perl objects can be array or
scalar based.

*So*, here's an option we haven't considered. Offer both mechanisms. And
try to make them look similar. Here's an example:

    yaml-obj: %
        #: class
        =: default
        attr1: foo
        attr2: bar

    perl-array-obj: (#class) @
        foo
        bar

and even:

    map: %
        #.int 32
        #.real 1.23E+7
        #.utf16 A string value

See, we *can* have our dog food and eat it too!

I actually need all of these forms to do Perl right. Java probably only
needs the coloring.

Some rules?

1) Colored classes always round-trip.
2) Inline classes only round trip if the implementation languages
support them.

> 
> A. This means that only "maps" in the
>    serialization format can be classes.

Nope :)

> 
> B. Given that Brian has suggested that
>    maps should be sorted by default and
>    also that the class should appear
>    before all of the other map entries,
>    I propose that a class is designated
>    by a ! (\x21) which is the first printable
>    past the space (\x20).   So, how
>    about "!class" ?  Or just "!" ?

But our emitter can use any sort order we want. (And that can be
overridden by the particular class) Choosing syntax based on percieved
sort order doesn't make sense. Our emitters should always put the color
info first.

> 
> C. I'd like the "default" key to be the
>    blank?  Thus,
> 
>     amap: %
>       !class: real
>       ""    : 3.23
> 
>    I like the default key to have some
>    sort of uniqueness, by using the blank
>    string, it is indeed unique since it has
>    length zero.   We could allow this to
>    be written as:
> 
>      amap: %
>        !: real
>         : 3.23
> 
>    I'm not sure... thoughts?

I like Oren's '=' personally.

> 
> D. We define that a YAML text A is
> E.  For each node N, a synthesized
> F.  For the pull (iterator, parser) API, define

I have had enough coffee to grok these. :)

> 
> G.  Drop the class syntax.

Nope.


Cheers, Brian

-- 
perl -le 'use Inline C=>q{SV*JAxH(char*x){return newSVpvf
("Just Another %s Hacker",x);}};print JAxH+Perl'

On Sun, Jun 03, 2001 at 11:07:37AM -0700, Brian Ingerson wrote:
| I think something like Oren's coloring scheme will
| definitely be needed.

Do you understand the API change?  getValue() or what ever we
call it, and then the substitutability property?

| This is the encoding I would use for special "YAML" objects in Perl.
| (Objects that inherit from the YAML class) With these objects you could
| override emitter methods like sort(), for instance. Anyway, I think the
| color scheme is probably a good encoding, and a necessary
| functionality.

Ok.

| *So*, here's an option we haven't considered. Offer both mechanisms. And
| try to make them look similar. Here's an example:
| 
|     yaml-obj: %
|         #: class
|         =: default
|         attr1: foo
|         attr2: bar

Ok.  This is cool.

|     perl-array-obj: (#class) @
|         foo
|         bar

Would not you write this...

      perl-array-obj: #class @
          foo
          bar

And, would you have an equivalence class
where the last is an abbreviation for...

      perl-array-obj:
          #: class
          =: @
              foo
              bar

In this way, only "maps" can be classes
in YAML... however, this doesn't mean
that a class must be a "map" in the native
language binding.

|     map: %
|         #.int 32
|         #.real 1.23E+7
|         #.utf16 A string value


I didn't get this one, you have a map (%),
but I don't see the colons...

| 1) Colored classes always round-trip.

Ok.

| 2) Inline classes only round trip if the
|    implementation languages support them.

I was just seeing the in-line form as
a syntax abbreviation for the former...
is this not workable?

| But our emitter can use any sort order we want. (And that 
| can be overridden by the particular class) Choosing syntax 
| based on percieved sort order doesn't make sense. Our 
| emitters should always put the color info first.

Ok.  # for class, and # is always first if it exists.

| > C. I'd like the "default" key to be the blank? 
|
| I like Oren's '=' personally.

Ok.  = it is.

| > D. We define that a YAML text A is
| > E.  For each node N, a synthesized
| > F.  For the pull (iterator, parser) API, define
| 
| I have had enough coffee to grok these. :)

Really?  This is a hard concept... but _very_ 
powerful as it allows backward-compatible schema
migration _without_ a re-write!

| > G.  Drop the class syntax.
| 
| Nope.

Ok.  But a hard question, it it a seperate 
construct, or just a syntax short-hand when
the only two map entries are "#" and "=" ?

Best,

Clark

"Clark C . Evans" wrote:
> |     perl-array-obj: (#class) @
> |         foo
> |         bar
> 
> Would not you write this...
> 
>       perl-array-obj: #class @
>           foo
>           bar

That's OK too.

> And, would you have an equivalence class
> where the last is an abbreviation for...
> 
>       perl-array-obj:
>           #: class
>           =: @
>               foo
>               bar
> 
> In this way, only "maps" can be classes
> in YAML... however, this doesn't mean
> that a class must be a "map" in the native
> language binding.

See other msg.

> 
> |     map: %
> |         #.int 32
> |         #.real 1.23E+7
> |         #.utf16 A string value
> 
> I didn't get this one, you have a map (%),
> but I don't see the colons...

My bad. Should have keys.

> 
> | 1) Colored classes always round-trip.
> 
> Ok.
> 
> | 2) Inline classes only round trip if the
> |    implementation languages support them.
> 
> I was just seeing the in-line form as
> a syntax abbreviation for the former...
> is this not workable?

Nope. See other msg.

> | > D. We define that a YAML text A is
> | > E.  For each node N, a synthesized
> | > F.  For the pull (iterator, parser) API, define
> |
> | I have had enough coffee to grok these. :)
> 
> Really?  This is a hard concept... but _very_
> powerful as it allows backward-compatible schema
> migration _without_ a re-write!

Sorry. Meant "I haven't had enough coffee to grok these. :)"

> 
> | > G.  Drop the class syntax.
> |
> | Nope.
> 
> Ok.  But a hard question, it it a seperate
> construct, or just a syntax short-hand when
> the only two map entries are "#" and "=" ?

See other msg.

-- 
perl -le 'use Inline C=>q{SV*JAxH(char*x){return newSVpvf
("Just Another %s Hacker",x);}};print JAxH+Perl'

| > | > D. We define that a YAML text A is
| > | > E.  For each node N, a synthesized
| > | > F.  For the pull (iterator, parser) API, define
| > |
| > | I have had enough coffee to grok these. :)
| > 
| > Really?  This is a hard concept... but _very_
| > powerful as it allows backward-compatible schema
| > migration _without_ a re-write!
| 
| Sorry. Meant "I haven't had enough coffee to grok these. :)"

Ok.  Substituability by example coming up.  Let us write
"X > Y" to mean "X is substituable for Y".  In other words,
if a program is expecting a YAML text structured like Y, it
will happily accept a YAML text structured like X.  Take
the following three YAML texts: A, B, and C.

Example A
~~~~~~~~~
  sample: value


Example B
~~~~~~~~~
  sample: %
    =     : value
    added : info

Example C
~~~~~~~~~~
  sample: %
    = : @
     value
     value2
    added: info


Here, we have A < B and B < C.  Substituability is transitive, 
thus A < C as well.  Note, that neither A > B, B > C, nor A > C 
are true statements.  

Why substitutability?  This propery is important since it allows
further information to be added to a YAML text without breaking
older software.  In other words, it allows for "forward 
compatibility", letting old programs handle new data.

How substitutability?  For each node, aNode, we introduce 
a synthesized attribute, asScalar.  aNode.asSclar() is 
defined to be:

   (a) aNode, if aNode is already a scalar.
   (b) aNode.firstChild().asScalar(), if aNode is a list.
   (c) aNode.getChild("=").asScalar(), if aNode is a map.

Ok.  Let's see how this works on a program *expecting*
a structure just like example A, a single map having
a key "sample".   It would do...

   topMap.getChild("sample").asScalar()

This would return the scalar node "value".   When this
code is executed on B and C, it returns... guess what?
Yes, a single scalar node, "value".

Thus, the above code, written to accept data structured
like A, can now happily accept data structured like
B or C without _any_ code changes.   

This gives programs which are based on YAML that use
the asSclar() synthesized attribute liberally to be
"forward compatible" with "substituable" changes in
the YAML file.

asSclar() can be implemented as a property of
a random access YAML Node, or it could even
be implemented in the parser or emitter interfaces!

Best,

Clark

P.S.  This is what Oren and I mean by "color".  This 
allows a data file to be "colored" by attributes 
recursively as required *without* breaking older
programs!