YAML Ain't Markup Language

Clark C . Evans [mailto:cce@...] wrote:
> | Split Spec...
> 
> - I like the table of contents page, could this be
>   the top level page rather than on a separate page?

I suppose we could. I like the short list of sections, however; I wouldn't
want to give it up.

> - Do we need to repeat all of the header stuff
>   for each section?  This gets tedious, perhaps
>   something like:
> 
>     This is a section of the YAML specification,
>     http://yaml.sourceforge.net/16jun2001.html 
> 
>   They can go here for the header

Well, the previous versions list is expected to start being different
between the different sections. (In the next draft, some sections will have
a new version and some won't). The status is already different... Perhaps
the best way would be to remove, in the sub-sections, the previous versions
before 16jun2001 - that is, include just the last version where everything
was together. This would cut down the amount of boilerplate somewhat.

> | Cyclical Graph
> 
> I was thinking that acyclic would allow for stream
> based processing since forward-based references
> were not allowed.  In otherwords, the * has to
> occur after the corresponding &.  Brian?  Are cyclic
> references required?

Why are forward references required for serializing cyclical graphs? Just do
a DFS on the graph, and reference back to any node you already visited. Here
are 1, 2 and 3 node cyclical graphs:

cycles: @
  One node cycle
  %
    name: &001 a
    links: @
      *001
  Two node cycle
  %
    name: &001 a
    links: @
      %
        name: b
        links: @
          *001
  Three node cycle
  %
    name: &001 a
    links: @
      %
        name: b
        links: @
          %
            name: c
            links: @
              *001

Have fun,
    Oren Ben-Kiki

On Sun, Jun 24, 2001 at 04:30:19PM +0200, Oren Ben-Kiki wrote:
| Clark C . Evans [mailto:cce@...] wrote:
| > | Split Spec...
| > 
| > - I like the table of contents page, could this be
| >   the top level page rather than on a separate page?
| 
| I suppose we could. I like the short list of sections, however;
| I wouldn't want to give it up.

Ok.  Let's put the short list of sections first, then
followed by the table of contents in all of its glory.

Alternatively, put the table of contents in *each* 
of the subordinate files at the top.  Thus, the main
binder then point directly to the table of contents
for each of the sections.

| > - Do we need to repeat all of the header stuff
| >   for each section?  This gets tedious, perhaps
| >   something like:
| > 
| >     This is a section of the YAML specification,
| >     http://yaml.sourceforge.net/16jun2001.html 
| > 
| >   They can go here for the header
| 
| Well, the previous versions list is expected to start being different
| between the different sections. (In the next draft, some sections will have
| a new version and some won't). The status is already different... Perhaps
| the best way would be to remove, in the sub-sections, the previous versions
| before 16jun2001 - that is, include just the last version where everything
| was together. This would cut down the amount of boilerplate
| somewhat.

I guess this would help.  Also having each section point
directly to the table of contents would also help.  Having
to "wade" through two or more pages of header information
for each section is tedious.

| > | Cyclical Graph
| 
| Why are forward references required for serializing cyclical graphs?

*blush*  Ok, but we still allow for "backward-only references"?

Thank you _so_ much,

Clark

Clark C . Evans [mailto:cce@...] wrote:
> On Sun, Jun 24, 2001 at 04:30:19PM +0200, Oren Ben-Kiki wrote:
> | Clark C . Evans [mailto:cce@...] wrote:
> | > | Split Spec...
> | > 
> | > - I like the table of contents page, could this be
> | >   the top level page rather than on a separate page?
> | 
> | I suppose we could. I like the short list of sections, however;
> | I wouldn't want to give it up.
> 
> Ok.  Let's put the short list of sections first, then
> followed by the table of contents in all of its glory.

OK.

> Alternatively, put the table of contents in *each* 
> of the subordinate files at the top.  Thus, the main
> binder then point directly to the table of contents
> for each of the sections.

I'd like to keep the "full TOC" as a single, separate document. How about we
change the pointer from the short list of sections to point to the actual
start of the document (the same place that the expanded TOC is currently
pointing to)? This way when you click on "2 Serialization" in the short list
you get straight to the text, no annoying headers unless you page up for
them.

> | > | Cyclical Graph
> | 
> | Why are forward references required for serializing cyclical graphs?
> 
> *blush*  Ok, but we still allow for "backward-only references"?

Yes, that's the wording. BTW, from a glimpse in yaml.h it seems you assume
anchor strings are always numbers in the range 0 - (2^32 - 1); should we
make this a requirement?

I also just noticed we don't have a production for null nodes (does your API
support them, BTW?). There's always something...

Have fun,

    Oren Ben-Kiki

On Mon, Jun 25, 2001 at 07:56:07AM +0200, Oren Ben-Kiki wrote:
| Yes, that's the wording. BTW, from a glimpse in yaml.h it
| seems you assume anchor strings are always numbers in the
| range 0 - (2^32 - 1); should we make this a requirement?

Yep.

| I also just noticed we don't have a production for null 
| nodes (does your API support them, BTW?). There's 
| always something...

I think we can support null nodes via color.  Speaking
of the API.  I think that I'm going to re-write it
using a very weak subset of C++ rather than C.  Why?

  - The iterator and visitor mechanisms are
    interfaces (aka function tables).  No use
    making our own function table mechanism
    when C++ will do it for us.

  - The "key" should implement a counted 
    pointer or some other mechanism to
    help the programmer manage who owns
    the actual memory; for the pull interface
    it really can't be the producer or
    the consumer.

  - I need the notion of an istream and ostream.
    No use reinventing the wheel (although I've
    heared that iostreams are much slower than
    fread/fwrite).

  - Most compliers support a simple subset
    of C++ these days... no point in seriously
    trying to work around.  For those that 
    do not support C++, the subset is so
    minimal that one could use cfront...

Thoughts?

Clark

Clark C . Evans [mailto:cce@...] wrote:
> On Mon, Jun 25, 2001 at 07:56:07AM +0200, Oren Ben-Kiki wrote:
> | Yes, that's the wording. BTW, from a glimpse in yaml.h it
> | seems you assume anchor strings are always numbers in the
> | range 0 - (2^32 - 1); should we make this a requirement?
> 
> Yep.

Well, I guess 2^23 nodes should be enough for everybody :-)

> | I also just noticed we don't have a production for null 
> | nodes (does your API support them, BTW?). There's 
> | always something...
> 
> I think we can support null nodes via color.

Huh? Consider the single line document:

null: ~

I don't see how it could be done as a color. It seems as though it is a
separate node type - similar to a reference node. For example, it has a
parent, a key or an index, etc. 

> Speaking
> of the API.  I think that I'm going to re-write it
> using a very weak subset of C++ rather than C.

I don't think it is a good idea:

- There's a benefit for using ANSI C, especially for the lower end (embedded
systems etc.).

- It seems trivial to convert a "weak C++" API to a proper C one: convert
each class to a struct of function pointers and add a 'self' parameter to
each method.

- Relying on things like istream/ostream in a C API is impossible anyway -
it is one thing to assume the complier knows what an interface is, and a
completely different thing to drag the C++ I/O library into a program!

The current yaml.h file is probably the right approach for purely-streaming
C-only API. You did an admirable job in unifying the push and pull APIs. I'm
a bit more ambitious. I want the pull/push APIs to be *exactly* the
iterator/visitor APIs to the random access data structures.

This is easy enough to do for Perl and Python (or even Java) which don't
have a developed iterator concept (they have 'next' - fine, so do we, we can
be compatible with the "standard" iteration idioms).

In C, "anything goes" - there are no standard iterator/visitor idioms. So
yaml.h is probably the best approach you can take there. I'd still like to
see it integrated with a random access structure, however! And I do have
some technical nits to pick there - I need to go over it carefully first,
though.

In C++, however, my ambitious requirement above means being STL-friendly to
some degree. You'd also want to use the standard string class - and
ownership issues may be handled to some degree by auto_ptr - and so on. In
short, I think it is going to be hard to keep the C and C++ APIs compatible.
It is probably not going to be practical to even layer the C++
implementation on top of the C one.

Thoughts?

Have fun,

	Oren Ben-Kiki

On Mon, Jun 25, 2001 at 04:37:11PM +0200, Oren Ben-Kiki wrote:
| null: ~

Ok.  Let's add a node type then.

| > Speaking of the API.  I think that I'm going to 
| > re-write it using a very weak subset of C++
| > rather than C.
| 
| I don't think it is a good idea:
| 
| - There's a benefit for using ANSI C, especially for the 
|   lower end (embedded systems etc.).
| 
| - It seems trivial to convert a "weak C++" API to 
|   a proper C one: convert each class to a struct of
|   function pointers and add a 'self' parameter to
|   each method.

This is what I'm doing.  However, to be compatible
with COM, I should re-write it so that each "object"
is a pointer to a pointer to the function table.  And 
then I should leave the first 3 function pointers
blank (these are needed for IUnknown).

I'd like the C implementation to be the standard COM 
binding so that Visual Basic, and any other Windows 
based object-oriented system can use YAML via COM.

| - Relying on things like istream/ostream in a C API 
|   is impossible anyway - it is one thing to assume 
|   the complier knows what an interface is, and a
|   completely different thing to drag the C++ I/O 
|   library into a program!

Ok.
 
| The current yaml.h file is probably the right approach for
| purely-streaming C-only API. You did an admirable job in 
| unifying the push and pull APIs. I'm a bit more ambitious.
| I want the pull/push APIs to be *exactly* the
| iterator/visitor APIs to the random access data structures.

I'd like to hear your suggestions before I go off and
start "implementing" first thing next week.  (I'm on
a tight deadline now... otherwise I'd be doing it this week).

| This is easy enough to do for Perl and Python (or even Java)
| which don't have a developed iterator concept (they have 
| 'next' - fine, so do we, we can be compatible with the 
| "standard" iteration idioms).

Right, and the Python binding (over the C interface)
will support python-style iterators.

| In C, "anything goes" - there are no standard iterator/visitor
| idioms. So yaml.h is probably the best approach you can take there.
| I'd still like to see it integrated with a random access structure,
| however! And I do have some technical nits to pick there - I 
| need to go over it carefully first, though.

Please do...
 
| In C++, however, my ambitious requirement above means being 
| STL-friendly to some degree. You'd also want to use the 
| standard string class - and ownership issues may be handled 
| to some degree by auto_ptr - and so on. In short, I think
| it is going to be hard to keep the C  and C++ APIs compatible.

Right, which is why I was thinking more the COM route.

| It is probably not going to be practical to even layer the C++
| implementation on top of the C one.

Well, we could have a thin wrapper... but then this
wrapper might not be STL compatible.  However, if
we can make the C interface like STL, this would
at least reduce the impediance mis-match.

Best,

Clark