[Yaml-core] (backfill) YAML Meeting: Options for Scalar Syntax

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

----- Forwarded message from "Clark C . Evans" <cc...@cl...> -----
Date: Thu, 17 May 2001 14:20:50 -0500
From: "Clark C . Evans" <cc...@cl...>
To: Oren Ben-Kiki <or...@ri...>,
	Brian Ingerson <briani@ActiveState.com>
Subject: YAML: Scalar Syntax Quoting / Folding

Ok.  Here is a summary of the concensus thus far:

 1. It is agreed that whitespace folding with
    C style escaping for whitespace \n and \t 
    is very useful, especially in the context
    of indented hierarchy.

 2. It is agreed that some sort of MIME
    mechanism will be included so that images
    and large formattetd text can be specified as 
    a scalar value without disrupting the tree

 3. It is agreed that for ASCII art, where 
    spacing is important, that the whitespace 
    folding technique is very ugly and that we 
    should find an additional method beyond
    the attachment and escaping mechanism is needed.

 4. Due to rfc822 compatibility, we must allow
    a scalar to start right after the colon
    and continue on subsequent lines, thus 
    blurring the difference between "single"
    and "multi-line" scalar values.

 5. We would like class names, reference 
    identifiers, and other meta data to occur on
    a single line along with the scalar value.
    
Given this concensus we have the following options:

  A. Only have whitespace folding and attachments,
     only allow single line scalars without meta-data.

     Problem: Does not solve #3 and #5

  B. Distinguish between single and multiple line values.
     Only allow single line scalars without meta-data.
     Perserve spacing for single-line scalars. 

     Problem: Prevents #4, #5 and is a weak
              solution to #3 due to single line.
     ...

     Notes:  There are variants on A and B
             where we allow scalar and meta
             data on the same line, but this
             does not help #3. 

  C. Distinguish between single and multiple line
     values, allowing single line scalars with 
     meta data, or one line preserved space 
     scalars using quotes.

     Problem:  Still bad for #4 due to the 
               distinction.  And also limits
               #3 to a single line of content.

     one   : $(0003) "quotes required"
     two   : "space   is preserved"   
     three : This is folded and can
             be on multiple lines.

  D. Allow for multi-line quoted values, where
     each line has a begin and end quote.  
     Require quotes when the value contains
     one of the special characters.  This is
     all or nothing, if one line is quoted,
     all must be quoted.  All other whitespace
     (tabs and new lines) must be escaped.

     Problems: This makes #3 (art) easier.  
               And doesn't really impact much else,
               although it adds another special
               character which folded content
               cannot begin with.


      one   : $(0003) "quotes required"
      two   : "space   is preserved"
      three : This is folded and can
              be on multiple lines.
      four  : "This is a quoted single, mixed, or multi "
              "line value.     Spaces are preserved "
              "just like C strings.  Also like C strings, "
              "\n and \t escapes are necessary for carrriage "
              "returns."

  E. Similar to D, but allow quotes to be mixed
     with folded text.  In this case, the \  escape
     for a space isn't required, but \" must be
     quoted.  Much more flexiblity.
    
     Problems: This may be incompatible with rfc822
               (in fact, I think it is).  Futher,
               it is a bit harder for a human/parser
               to grok.

     one   : $(0003) "quotes required"
     two   : "space   is preserved"
     three : This has "is    mixed" spacing
             that can continue on multiple lines.  A \n
             is still needed for new lines.

  F. Allow for multi-line whitespace significant lines  
     to begin with a | symbol.  Much like D, only that 
     | instead of " and a terminating character is not
     needed.  However, this does not look palatable 
     unless used in single xor multi line version, without
     amitting a mixed line version.  Further, with this
     mechanism, we can suspend slash escaping?  

     Problems: Most programmers will be familar
               with quoting and not with | blocks.
               This adds a special character, |, 
               which folded strings cannot include.

     one   : $(0003) quotes not required
     two   : |space   is preserved
     example f: $(0002)
         |With the pipe on the begin marker,     extra 
         |spaces and carriage returns are significant.
         |   Perhaps \ need not be escaped?
         |This one ends with an extra new line.          
         | 

Ok.  Have I missed anything?  I think I prefer choice "D".
     
Best,

Clark             
          


    

----- End forwarded message -----