YAML Ain't Markup Language

----- Original Message -----
From: "Oren Ben-Kiki" <orenbk@...>
> [...]
> How would you all feel about "...\n" as a document terminator and "===\n"
as
> a stream terminator?
>
> One could say that this is outside the scope of YAML and should be
addressed
> by another spec (such as MIME multi-part messages). However, I don't see a
> MIME-based solution working well for ysh, or anything similar to it.
>

Let's say you have a loop like this:

while 1:
    doc = yaml.LoadDocument()
    if doc is None:
        break
    processDoc(doc)

What should yaml.LoadDocument return when it encounters the "===\n" document
terminator?  It can't really return None, because that would be ambiguous.
Think about what this doc also returns:

--- ~

You could make LoadDocument throw a particular type of exception when the
stream ends, but that seems kludgy.  Another kludge is to have LoadDocument
return a tuple, with the data and the state of the stream.

You could almost leave it up to the application to specify its own
terminator.  The data might know that "EOY" is never a valid piece of data
for itself, so it would use this to terminate the YAML part of the stream:

--- EOY

On Thu, Jul 04, 2002 at 02:53:26AM -0400, Oren Ben-Kiki wrote:
 Neil Watkiss [mailto:neilw@...] wrote:
| > > Now, '...' as a stream terminator (as opposed to a document 
| > > terminator) is an interesting thought... I see how that may 
| > > be useful, while the usefulness of a document terminator 
| > > isn't clear to me.

If you want, you can think of "..." as a stream-pause indicator,
this would better express its intent.  It is used to let someone
on the other end of the stream know that there may be more content
coming, but just not yet.

| > 
| > Personally, I see a stream as something which, by definition, 
| > never ends...
| >
| > Most streaming protocols already have very well-defined 
| > semantics for marking
| > the end of a stream. Consider:
| > 
| >     close()
| >     fclose()
| >     select()
| >     EOF
| 
| That assumes that the *physical* stream contains just the YAML stream and 
| nothing else.

I think that this is 90% of the use case; YAML on the wire or in
a file where the stream itself has a mechanism to indicate that 
it has finished.  The other 10% is where YAML is part of a 
container (ysh), and in this case, the container's mechanism 
is more important.   

Hmm.  Perhaps "..." is a stream escape marker, indicating that
the current document has ended and that remaining content is
according to the stream's requirements.   In most cases, the
only allowable thing is a new document since the stream has
that rule; in the case of ysh, it allows for other types of
text chunks (besides YAML).

| Also, is it completely unreasonable to expect to be able to feed several
| documents to ysh "in one go"? Using '...' as a document terminator doesn't
| help in doing that.
| 
| Now, I still see the usefulness of '...' as a document separator for cases
| where a stream of documents is sent in a socket etc. So I'm *not*
| challenging that.
| 
| I'm just wondering whether it doesn't make sense to also provide a stream
| terminator for use when a YAML stream is embedded inside some other text
| (such as a ysh command stream).
| 
| How would you all feel about "...\n" as a document terminator and "===\n" as
| a stream terminator?
| 
| One could say that this is outside the scope of YAML

I think so; but perhaps a more flexible viewing of "...\n" is in order.

Best,

Clark

-- 
Clark C. Evans                   Axista, Inc.
http://www.axista.com            800.926.5525
XCOLLA Collaborative Project Management Software