RE: [Yaml-core] Proposed Changes to YAML Spec

[Oren Ben-K. <or...@ri...>]

Brian Ingerson [mailto:in...@tt...] wrote:
> It seems you are bent on reducing this to two scalar rules. 
> Why not just allow three. (It's a luckier number :)

I also came to this conclusion. Two just isn't enough. We need three because
there are three common cases:

- Verbatim ("block"). Rarely used, but then it is a must-have (e.g. large
amounts of code).

- "Everything possible" ("quoted"). More common, but more verbose, is vital
for non-printables, indicators, etc.

- Plain text ("simple": unquoted, line-wrapped, no escapes). To me this is
the most useful type of all. It is the most commonly used format, it is the
least verbose, and is what we tend to write in all our examples.

We have a difference of opinion on how important "simple" text is. You want
to restrict it to one-liners for some reason. I'm not clear on why. I have
two problems with this restriction:

- You can no longer generate RFC822 headers using a YAML emitter.

- You can no longer cut&paste text from, say, an E-mail message, or from a
notepad file, or whatever, into a YAML document without worrying about
escaping.

Example:

invoice: %
    description:
        The ACME 2001 Widget is a unique product which
        will replace all the tools in your house! Chosen
        as "best product of the year" by the Loony Toons
        Review (TM) and personally recommended by Wile E.
        Coyote, Genius!

Now, according to your proposal, I'd have to quote this text,
escape the ", etc. Ugh.

So, how about the following compromise. We keep 3 types of text.

Quoted: as today.

Block: as you proposed, with the slight modification it always has an
indicator character: \ if there is no trailing newline (like today) and | if
it does have a trailing newline.

Simple text: like quoted text except that no escaping is done.

As for keys. There's no theoretical reason not to allow all three types for
keys (that is, there's no ambiguity in the syntax and parsing is not a
problem). That said, I agree to restricting keys to either quoted text or
"single-line simple text without :". The need for more complex keys is rare.

Samples:

block: |
    with trailing newline.
another: \
    without trailing newline.
"foo\nbar\n" : "quoted text"
foo bar: simple text
    may be multi-line
simple:
    may start on next line
quoted:
    "may do either as well".

Compared to your proposal:

> 1) Single Value
>    - Always on same line as key
No; and may be multi-line (important!)
>    - Not escaped (verbatim)
Yes
>    - Can't be used for special values like ' ', '%', '@', etc.
No (can be used as long as they aren't the first character)
>    - No trailing newline
Yes (but see below)
>    - Leading/Trailing whitespace not significant
Yes

> 2) Quoted
>    - Supports single and multi-line values
yes
>    - Same rules as always
Yes (but see below)

> 3) Block
>    - Always start on next line
Yes, but indicator required (| or \)
>    - Indenting required
Yes
>    - Bulleted in lists
Yes
>    - Not used for map keys
Yes

Pretty close agreement...

As for the "see below"s: I had an unrelated idea about empty lines (now that
we allow them). How about the semantics of an empty line in a quoted/simple
text would be the same as "\n" (a "hard" newline)? That would allow:

text:
   Text for first
   paragraph.

   Text for second
   paragraph.

Neat, right? readability rules!

> I'll tell you what. If you support me on the above, then I 
> will support "full bulleting" for lists:

Does the above count as good enough an agreement? :-)

Have fun,

	Oren Ben-Kiki