yaml Wiki & Documentation Rss Feed

Updated Wiki: Building the Code

BurtHarris — Mon, 15 Aug 2011 00:08:07 GMT

I use Visual studio to build the projects. There are two solutions files under /Yaml/Main:

YamlCore.sln - builds just the core assemblies & core unit test projects
YamlLanguage.sln - Builds core and vs language integration projects

YAML editor build prerequsites:

  - Name: Microsoft Visual Studio 2010 SP1
    URL:  http://www.microsoft.com/download/en/details.aspx?id=23691
    Note: I'm using ultimate edition, but I think this should all work with professional edition.   
          However I'm not sure any of the free (Express) edition will do, please provide feedback if you try.
  
  - Name: Microsoft Visual Studio 2010 SDK SP1
    URL:  http://www.microsoft.com/download/en/details.aspx?id=21835
    
  - Name: WiX Toolset v3.5 
    URL:  http://wix.codeplex.com/releases/view/60102
    Date: January 31, 2011

Updated Wiki: Documentation

BurtHarris — Mon, 15 Aug 2011 00:07:06 GMT

Currently, this YAML package supports building two different versions of code, code based on .NET 2.0-3.5 , and code based on .NET 4.0. Since Powershell is still .NET 2.0 based, we'll strive to keep this verion supported, but moving forward .NET 4.0 has key parts of the Dynamic Language Runtime integrated into it which makes it much more attractive, and the editor add-in mechanisms for Visual Studio 2010 (based on .NET 4.0) are much more power than the older visual studio version. Both versions of the library, and the addins for both versions of Visual Studio will build with Visual Studio 2010 moving forward, but that does't require all users (as opposed to developers) to make the move this year.

Building the Code

Yaml_Specification_Issues

Updated Wiki: MinuteFive

BurtHarris — Mon, 21 Dec 2009 21:11:28 GMT

Minute Five: Is That All???

At this point it may seem like there isn't much to YAML. It's just a bunch of lists and dictionaries?

Well, these are just the basics here and our five minutes are about up. Before we go, one last concept.

Here's one person's record of how long their trip through this tutorial took:

---
name: Dirk Hockeybranch
minutes spent: 
 - 1.02
 - 1.34
 - 0.7
 - 0.89
 - 0.94

Above we have a list (sequence) nested inside of a dictionary (map). Each item in the list represents the number of minutes spent on each page. If everyone sent us documents describing their time like this, then we could compile a more accurate name for this tutorial. Such as: YAML in Five-Point-One-Two Minutes. That would be pretty slick.

One very smart YAML user decides to use an inline sequence to record their time:

---
name: Dirk Hockeybranch
minutes spent: [1.02, 1.34, 0.7, 0.89, 0.94]

For short lists, you can simply put the entire list on a single line. Separate it by commas and put brackets around it.

Inline maps are also available:

---
minutes spent: {one: 1.02, two: 1.34, three: 0.7,
                four: 0.89, five: 0.94}

Please beware, though. Blocks are not available in inline sequences or maps.

Conclusion

Check the time. Where are we at now? Five minutes? Ten minutes?

Now it's your turn to write some YAML! Add a comment below with your time to compelte the list! For extra credit, you can add a key called comments with your reaction to this tutorial.

If you'd like to further your study of YAML, I'd suggest taking a look at the YAML Cookbook. The Cookbook will go into more detail on each of the concepts above. I think you'll be surprised at how much more YAML has to offer.

Most of all: thanks for your time!

Want to learn more? YamlTheSecondFiveMinutes

Updated Wiki: MinuteFour

BurtHarris — Mon, 21 Dec 2009 21:10:17 GMT

Minute Four: A Lot More Words

You receive a message back from the post office with some comments.

---
Concerning Car Washes: >

  We are sorry to have misplaced this letter.
  We were told by a reliable source that you
  were the owner of "Hank Bros.: the Car Wash!".

  Sorry.

The post office has screwed up, but they've also taught us about a very cool feature in YAML. They've used a block in their message.

In YAML, a block is a block of text. The block is indented one space or more.

Notice the little angle bracket: >. This indicates the beginning of a folded block. The folded block means that sentences which are right next to each other flow together as a paragraph. The block is read as a human would read it.

A YAML reader sees the above block as two lines, separated by a single carriage return.

Controlling Words

Their message continues.

Concerning "Jim O'Connor": |

  You are receiving Jim O'Connor's mail for several reasons:
  - The nameplate on your mailbox still says his name.
  - He has told our postman that you screen his mail.
  - He is living in your ceiling.
  - He held a raygun to the postman's head.

Hmm. This guy sounds totally eccentric. But notice that instead of an angle bracket, the post office has placed a straight line before the block. What could this mean?

A straight line (or pipe) character indicates the beginning of a literal block. The literal block means that every sentence is each separate in its own paragraph. The block is treated literally as a computer would read it.

A YAML reader sees the above block as five (six? –MQR) lines (the first line is blank).

Let's wrap this up: MinuteFive

Updated Wiki: MinuteThree

BurtHarris — Mon, 21 Dec 2009 21:09:47 GMT

Minute Three: In Your Mailbox

Let's slow down for this third minute. We can't have your friend harassing you any further or you'll be storming off soon.

Instead, we're going to take a walk and pick up the mail. You live in an apartment complex and your mailbox is a little slot next to hundreds of other slots.

You check your mailbox and find that you have five items of mail. Two for your neighbor, Jim O'Connor, and one for a business called "Hank Bros.: the Car Wash!". The other two letters are for you.

You decide to start keeping a record of the items you find in your mailbox. You're going to send a detailed report to the post office so they can see what a mess this is for you.

You start a new YAML document with today's date and the contents of your mailbox:

---
date: 2003-07-25
letters to:
  "Hank Bros.: the Car Wash!": 1
  Jim O'Connor: 2
  Myself: 2

Here we have a map inside of another map. The first map contains a key: letters to. The value for this key is a nested map, which is indented.

In PHP or Ruby:

print $mailbox['letters to']['Myself'];

Would print:

You'll also notice that we've quoted "Hank Bros.: the Car Wash!". This is because the name includes a colon. Some characters need to be quoted to ensure that there is no confusion about what is a key and what is a value.

Almost there! MinuteFour

Updated Wiki: MinuteTwo

BurtHarris — Mon, 21 Dec 2009 21:09:17 GMT

Minute Two: A Simple Dictionary

You take so long reading the Harry Potter books that your friend sends you an updated list. He has included the authors' names this time.

Stanislaw Lem: Memoirs Found in a Bathtub
Neal Stephenson: Snowcrash
Daniel Clowes: Ghost World

The dictionary above has no order, but matches author's names with the book titles. Your friend's hope is that having the author's name will help you find the book.

In YAML, such a dictionary is called a map. Maps are commonly used to pair data up. On the left side of the colon is the key. On the right is the value.

The key is used as an index for retrieving data from a map.

In PHP or Ruby:

print $books_by_author['Daniel Clowes'];

Would print:

Ghost World

A Map In Sequence

Your friend sends you an updated list that includes the author's name, the title of book and the order in which he wants you to read them.

---
- Stanislaw Lem: Memoirs Found in a Bathtub
- Neal Stephenson: Snowcrash
- Daniel Clowes: Ghost World

Each item in the sequence above contains a map. When one sort of collection contains another, this is called nesting.

Next up: MinuteThree

Updated Wiki: MinuteOne

BurtHarris — Mon, 21 Dec 2009 21:08:51 GMT

Minute One: A Simple List

Your friend e-mails you a list of books:

- Memoirs Found in a Bathtub
- Snow Crash
- Ghost World

He has also requested that you read them in the order listed. He wants to talk to you about them in order as you read them. He's kind of anal.

In YAML, this sort of list is called a sequence. A sequence provides a set of data and gives it an order. When you load this list into your program, the order is kept.

In many agile languages, you can access a sequence by using a numeric index. An index of 0 indicates the first item in a sequence. In PHP, Perl, or Ruby:

print $book_list[0];

Would print:

Memoirs Found in a Bathtub

Which is the first item in the book list.

More Lists

Lists can contain all sorts of data:

---
- 1           # Numbers
- Snow Crash  # Strings
- 2003-07-24  # Dates

The above list is preceded by three dashes. These three dashes are the document separator. A document separator can indicate the start of a YAML document.

It can also separate multiple documents. You have your own stack of books that you want to read first:

---
- Harry Potter and the Prisoner of Azkaban
- Harry Potter and the Goblet of Fire
- Harry Potter and the Order of the Phoenix
---
- Memoirs Found in a Bathtub
- Snow Crash
- Ghost World

On to MinuteTwo

Updated Wiki: Yaml in 5 minutes

BurtHarris — Mon, 21 Dec 2009 21:07:24 GMT

YAML is a human friendly data serialization standard for all proramming languages

YAML is extremely simple to learn. The basics are extraordinarily simple. You may even find that you have unintentionally used YAML syntax when building lists or simple file formats.

It also helps if you have experience with any agile language (such as Ruby, Python, Perl or PHP). YAML was designed to suit these languages well and borrows a few basic ideas from them.

For an example of YAML, and links to all sorts of related information, see http://yaml.org. For more invormation on this Codeplex project, see http://yaml.codeplex.com.

Can You Learn YAML in Five Minutes?

This tutorial, is originally from yaml.kwiki.org, gives you a brief introduction to YAML, and takes most people less than 5 minutes to complete. Its been cached here since the other site isn't always available.

And look at the clock before you start. Jot the time down and we'll see how fast you are.

Click to begin: MinuteOne

Updated Wiki: Yaml in 5 minutes

BurtHarris — Mon, 21 Dec 2009 21:05:57 GMT

YAML is a human friendly data serialization standard for all proramming languages

Can You Learn YAML in Five Minutes?

This tutorial, is originally from yaml.kwiki.org, gives you a brief introduction to YAML, and takes most people less than 5 minutes to complete. Its been cached since the other site isn't always available.

And look at the clock before you start. Jot the time down and we'll see how fast you are.

Click to begin: MinuteOne

Updated Wiki: Yaml in 5 minutes

BurtHarris — Mon, 21 Dec 2009 21:02:18 GMT

YAML is a human friendly data serialization standard for all proramming languages.

For an example of YAML, and links to all sorts of related information, see http://yaml.org. For more invormation on this Codeplex project, see http://yaml.codeplex.com.

Can You Learn YAML in Five Minutes?

This tutorial, is originally from yaml.kwiki.org, gives you a brief introduction to YAML, and takes most people less than 5 minutes to complete. Its been cached since the other site isn't always available.
---

YAML is extremely simple to learn. The basics are extraordinarily simple. You may even find that you have unintentionally used YAML syntax when building lists or simple file formats.

It also helps if you have experience with any agile language (such as Ruby, Python, Perl or PHP). YAML was designed to suit these languages well and borrows a few basic ideas from them.

And look at the clock before you start. Jot the time down and we'll see how fast you are.

Click to begin: MinuteOne

Updated Wiki: Yaml in 5 minutes

BurtHarris — Mon, 21 Dec 2009 21:01:49 GMT

YAML is a human friendly data serialization standard for all proramming languages.

For an example of YAML, and links to all sorts of related information, see http://yaml.org. For more invormation on this Codeplex project, see http://yaml.codeplex.com.

Can You Learn YAML in Five Minutes?

This tutorial, is originally from yaml.kwiki.org, gives you a brief introduction to YAML, and takes most people less than 5 minutes to complete. Its been cached since the other site isn't always available.
---

YAML is extremely simple to learn. The basics are extraordinarily simple. You may even find that you have unintentionally used YAML syntax when building lists or simple file formats.

It also helps if you have experience with any agile language (such as Ruby, Python, Perl or PHP). YAML was designed to suit these languages well and borrows a few basic ideas from them.

And look at the clock before you start. Jot the time down and we'll see how fast you are.

Click to begin: MinuteOne

Updated Wiki: Yaml in 5 minutes

BurtHarris — Mon, 21 Dec 2009 20:53:42 GMT

YAML is a human friendly data serialization standard for all proramming languages.

For an example of YAML, and links to all sorts of related information, see http://yaml.org. For more invormation on this Codeplex project, see http://yaml.codeplex.com.

Can You Learn YAML in Five Minutes?

This tutorial, is originally from yaml.kwiki.org, gives you a brief introduction to YAML, and takes most people less than 5 minutes to complete. Its been cached since the other site isn't always available.
---

YAML is extremely simple to learn. The basics are extraordinarily simple. You may even find that you have unintentionally used YAML syntax when building lists or simple file formats.

It also helps if you have experience with any agile language (such as Ruby, Python, Perl or PHP). YAML was designed to suit these languages well and borrows a few basic ideas from them.

And look at the clock before you start. Jot the time down and we'll see how fast you are.

Click to begin: MinuteOne

New Comment on "Yaml in 5 Minutes"

BurtHarris — Tue, 15 Dec 2009 22:00:36 GMT

Yaml is a data serialization language. It might be used for example for configuration files.

Updated Wiki: Home

BurtHarris — Sun, 13 Dec 2009 23:08:52 GMT

About YAML	Developer Page	Download link to the right -->

December 13, 2009
Three's a new download available of the 0.5 version of the Yaml Language Package. See the Download link to the right.
Features:

Yaml 1.2 compliance
Better error checking and reporting
Based on the Microsoft.NET Dynamic Language Runtime.

If you download and install this, please leave a reply on Beta editor feedback telling me how it went.

P.S. For those few of you who jumpped in and downloaded yesterday's upload (0.5.1212.0), please pick up a new copy with version (0.5.12130.0) to get some minor highlighting and colorization fixes.

January 19, 2009
Access to yaml.kwiki.org has been down for a long time. I used the wayback machine to retrieve a copy of Yaml in 5 Minutes and post it here. Its my favorite introduction to YAML.

New Year's 2009

Happy New Year! The first bits are now in beta. The first thing ready for use is a YAML editor, based on Visual Studio. Features include syntax-driven highlighting, dynamic error checking, and brace matching.

Updated Wiki: Home

BurtHarris — Sun, 13 Dec 2009 23:07:52 GMT

About YAML	Developer Page	Download link to the right -->

December 13, 2009
Three's a new download available of the 0.5 version of the Yaml Language Package. See the Download link to the right.
Features:

Yaml 1.2 compliance
Better error checking and reporting
Based on the Microsoft.NET Dynamic Language Runtime.

If you download and install this, please leave a reply on Beta editor usage notes telling me how it went.

P.S. For those few of you who jumpped in and downloaded yesterday's upload (0.5.1212.0), pick up a new copy with version (0.5.12130.0) to get some minor highlighting and colorization fixes.

January 19, 2009
Access to yaml.kwiki.org has been down for a long time. I used the wayback machine to retrieve a copy of Yaml in 5 Minutes and post it here. Its my favorite introduction to YAML.

New Year's 2009

Happy New Year! The first bits are now in beta. The first thing ready for use is a YAML editor, based on Visual Studio. Features include syntax-driven highlighting, dynamic error checking, and brace matching.

Updated Wiki: Home

BurtHarris — Sun, 13 Dec 2009 23:04:42 GMT

About YAML	Developer Page	Download link to the right -->

December 13, 2009
Three's a new download available of the 0.5 version of the Yaml Language Package. See the Download link to the right.
Features:

Yaml 1.2 compliance
Better error checking and reporting
Based on the Microsoft.NET Dynamic Language Runtime.

P.S. For those few of you who jumpped in and downloaded yesterday's upload (0.5.1212.0), pick up a new copy with version (0.5.12130.0) to get some minor highlighting and colorization fixes.

January 19, 2009
Access to yaml.kwiki.org has been down for a long time. I used the wayback machine to retrieve a copy of Yaml in 5 Minutes and post it here. Its my favorite introduction to YAML.

New Year's 2009

Happy New Year! The first bits are now in beta. The first thing ready for use is a YAML editor, based on Visual Studio. Features include syntax-driven highlighting, dynamic error checking, and brace matching.

Updated Wiki: Home

BurtHarris — Sun, 13 Dec 2009 08:39:21 GMT

About YAML	Developer Page	Download link to the right -->

December 12, 2009
Three's a new download available of the 0.5 version of the Yaml Language Package. See the Download link to the right.
Features:

Yaml 1.2 compliance
Better error checking and reporting
Based on the Microsoft.NET Dynamic Language Runtime.

January 19, 2009
Access to yaml.kwiki.org has been down for a long time. I used the wayback machine to retrieve a copy of Yaml in 5 Minutes and post it here. Its my favorite introduction to YAML.

New Year's 2009

Happy New Year! The first bits are now in beta. The first thing ready for use is a YAML editor, based on Visual Studio. Features include syntax-driven highlighting, dynamic error checking, and brace matching.

Updated Wiki: Yaml_Specification_Issues

BurtHarris — Wed, 09 Dec 2009 21:42:46 GMT

%YAML 1.2
--- 
Title:          YAML 1.2 problems/fixes with specification examples 

Based on:       http://yaml.org/spec/1.2/spec.html (3rd Edition, Patched at 2009-10-01)

Author:         Burt Harris

Last change:    2009-12-09 13:41 PST

Summary:        The new YAML 1.2 specification is great.   I've been using the 
                examples as part of my unit testing, and discovered a few
                small corrections I believe should be made.   These all seem 
                to be typos rather than any sort of change in the meaning of 
                the spec.

Example 5.11:   Examples differ in two places by letter case on word "Line".
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!str "Line break (no glyph)\n\
                          Line break (glyphed)\n"

Example 5.12:   For consistency, right hand side needs two !!str tags.

                I propose changing the right hand side to read:

                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "quoted"
                      : !!str "Quoted \t",
                      ? !!str "block"
                      : !!str "void main() {\n\
                        \tprintf(\"Hello, world!\\n\");\n\
                        }\n",
                    }

                
Example 6.21:   Block version is missing a required end-of-document indicator.

                I propose changing the _left_ hand side to read:
                
                    %TAG !m! !my-
                    --- # Type here
                    !m!light fluorescent
                    ...
                    %TAG !m! !my-
                    --- # Color here
                    !m!light green
                
Example 6.22:   Flow version isn't a sequence, doesn't match block version.
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                        !<tag:example.com,2000:app/foo> "bar"
                        ]

Example 6.23:   Perhaps it's intended to prove a point, but there
                seem to be gratuitous differences between left and 
                right hand version of this (e.g. number of anchors.)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ?  !!str &B1 "foo"
                      :  !!str "bar",
                      ?  !!str &B2 "baz"
                      :  *B1,
                    }

Example 7.1:    Map entries unnecessarily out-of-order (confusing.)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "First occurrence"
                      : &A !!str "Foo",
                      ? !!str "Second occurrence"
                      : *A,
                      ? !!str "Override anchor"
                      : &B !!str "Bar",
                      ? !!str "Reuse anchor"
                      : *B,
                    }

Example 7.10:   Extra comma in "Up, up, and away".
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!str "::vector",
                      !!str ": - ()",
                      !!str "Up, up, and away!",
                      !!int "-123",
                      !!str "http://example.com/foo#bar",
                      !!seq [
                        !!str "::vector",
                        !!str ": - ()",
                        !!str "Up, up and away!",
                        !!int "-123",
                        !!str "http://example.com/foo#bar",
                      ],
                    ]

Example 8.2:    Should newline after tab be preserved rather than folded?
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!str "detected\n",
                      !!str "\n\n# detected\n",
                      !!str " explicit\n",
                      !!str "\t\ndetected\n",
                    ]
                                    

Example 8.5:    Block version contains a double-down-arrow glyph, no longer a break 1.2.
                I propose changing the left hand side to read:
                
                    ·# Strip↓
                    ··# Comments:↓
                    strip: |-↓
                    ··# text↓
                    ··↓
                    ·# Clip↓
                    ··# comments:↓
                    ↓
                    clip: |↓
                    ··# text↓
                    ·↓
                    ·# Keep↓
                    ··# comments:↓
                    ↓
                    keep: |+↓
                    ··# text↓
                    ↓
                    ·# Trail↓
                    ··# comments.↓
                
                Should the last scalar in the flow version have two newlines?
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "strip"
                      : !!str "# text",
                      ? !!str "clip"
                      : !!str "# text\n",
                      ? !!str "keep"
                      : !!str "# text\n\n",
                    }
                    
                    

Example 8.10-8.13 :   Flow version is missing trailing backslash on first bullet line.
                The Block version of 8.12 & 8.13 is missing a final 's' on the final bulleted line
                
                I propose changing the left hand side on 8.12 & 8.13 to match 8.10, like this:
                    >

                     folded
                     line

                     next
                     line
                       * bullet

                       * list
                       * lines

                     last
                     line

                    # Comment                

                I propose changing the right hand side of all four to read:
                    %YAML 1.2
                    ---
                    !!str "\n\
                          folded line\n\
                          next line\n\
                          \  * bullet\n\
                          \n\
                          \  * list\n\
                          \  * lines\n\
                          \n\
                          last line\n"


Example 8.15:   Flow version missing a comma in inner sequence.
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!null "",
                      !!str "block node\n",
                      !!seq [
                        !!str "one",
                        !!str "two",
                      ],
                      !!map {
                        ? !!str "one"
                        : !!str "two",
                      },
                    ]
                    
Example 8.19:   Flow version has an extra comma on line 11.   In my parser, 
                this generates an extra unexpected !!null : !!null mapping
                entry at that point in the parse (is that right?!?)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!map {
                         !!str "sun" : !!str "yellow",
                      },
                      !!map {
                        ? !!map {
                          ? !!str "earth"
                          : !!str "blue"
                        }
                        : !!map {
                          ? !!str "moon"
                          : !!str "white"
                        },
                      }
                    ]

Example 8.21:   Flow version of folded and literal missing normalized newlines.   
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "literal"
                      : !!str "value\n",
                      ? !!str "folded"
                      : !<!foo> "value\n",
                    }                                    
                    
Example 9.3:    Block version - Comments not permitted in literals.

                I propose changing the _left_ hand side to read:
                
                    Bare
                    document
                    ...
                    # No document
                    ...
                    |
                    %!PS-Adobe-2.0
                    ...  #Looked like a directive, but the first line

                Flow version - Missing end-of-document indicator before 
                2nd YAML directive.   
                
                I propose changing the right  hand side to read:

                    %YAML 1.2
                    ---
                    !!str "Bare document"
                    ...
                    %YAML 1.2
                    ---
                    !!str "%!PS-Adobe-2.0\n"
                
                

Example 9.5:    Missing space in second YAML directive.
                
                I propose changing the _left_ hand side to read:
                    %YAML 1.2
                    --- |
                    %!PS-Adobe-2.0
                    ...
                    %YAML 1.2
                    ---
                    # Empty
                    ...
                
---  # YAML 1.1 # Old Specification issues: may be out of date
Example 9.1:   Trailing brace needs to be indented.
Example 9.7:   Trailing brace needs to be indented.
Example 9.12:  Output has extra second commas in "Up, up, and away"
Example 9.13:  Trailing brace needs to be indented.
Example 9.15:  How are content that looks like document indicators made safe?
Example 9.20:  Why doesn't tab (leading whitespace) counting a spaced line, 
               preserve the newline after it?
Example 9.23:  Shouldn't the PS in the "strip:" literal be reflected on output?
               Looks like it's been removed in 1.2 nearly identical example 8.5.
Example 10.7:  Does the empty key line needs a comma?
Example 10.7:  Does the line starting with "simple key" needs a comma?

Updated Wiki: Yaml_Specification_Issues

BurtHarris — Wed, 09 Dec 2009 21:42:11 GMT

%YAML 1.2
--- 
Title:          YAML 1.2 problems/fixes with examples specification

Based on:       http://yaml.org/spec/1.2/spec.html (3rd Edition, Patched at 2009-10-01)

Author:         Burt Harris

Last change:    2009-12-09 13:41 PST

Summary:        The new YAML 1.2 specification is great.   I've been using the 
                examples as part of my unit testing, and discovered a few
                small corrections I believe should be made.   These all seem 
                to be typos rather than any sort of change in the meaning of 
                the spec.

Example 5.11:   Examples differ in two places by letter case on word "Line".
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!str "Line break (no glyph)\n\
                          Line break (glyphed)\n"

Example 5.12:   For consistency, right hand side needs two !!str tags.

                I propose changing the right hand side to read:

                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "quoted"
                      : !!str "Quoted \t",
                      ? !!str "block"
                      : !!str "void main() {\n\
                        \tprintf(\"Hello, world!\\n\");\n\
                        }\n",
                    }

                
Example 6.21:   Block version is missing a required end-of-document indicator.

                I propose changing the _left_ hand side to read:
                
                    %TAG !m! !my-
                    --- # Type here
                    !m!light fluorescent
                    ...
                    %TAG !m! !my-
                    --- # Color here
                    !m!light green
                
Example 6.22:   Flow version isn't a sequence, doesn't match block version.
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                        !<tag:example.com,2000:app/foo> "bar"
                        ]

Example 6.23:   Perhaps it's intended to prove a point, but there
                seem to be gratuitous differences between left and 
                right hand version of this (e.g. number of anchors.)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ?  !!str &B1 "foo"
                      :  !!str "bar",
                      ?  !!str &B2 "baz"
                      :  *B1,
                    }

Example 7.1:    Map entries unnecessarily out-of-order (confusing.)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "First occurrence"
                      : &A !!str "Foo",
                      ? !!str "Second occurrence"
                      : *A,
                      ? !!str "Override anchor"
                      : &B !!str "Bar",
                      ? !!str "Reuse anchor"
                      : *B,
                    }

Example 7.10:   Extra comma in "Up, up, and away".
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!str "::vector",
                      !!str ": - ()",
                      !!str "Up, up, and away!",
                      !!int "-123",
                      !!str "http://example.com/foo#bar",
                      !!seq [
                        !!str "::vector",
                        !!str ": - ()",
                        !!str "Up, up and away!",
                        !!int "-123",
                        !!str "http://example.com/foo#bar",
                      ],
                    ]

Example 8.2:    Should newline after tab be preserved rather than folded?
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!str "detected\n",
                      !!str "\n\n# detected\n",
                      !!str " explicit\n",
                      !!str "\t\ndetected\n",
                    ]
                                    

Example 8.5:    Block version contains a double-down-arrow glyph, no longer a break 1.2.
                I propose changing the left hand side to read:
                
                    ·# Strip↓
                    ··# Comments:↓
                    strip: |-↓
                    ··# text↓
                    ··↓
                    ·# Clip↓
                    ··# comments:↓
                    ↓
                    clip: |↓
                    ··# text↓
                    ·↓
                    ·# Keep↓
                    ··# comments:↓
                    ↓
                    keep: |+↓
                    ··# text↓
                    ↓
                    ·# Trail↓
                    ··# comments.↓
                
                Should the last scalar in the flow version have two newlines?
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "strip"
                      : !!str "# text",
                      ? !!str "clip"
                      : !!str "# text\n",
                      ? !!str "keep"
                      : !!str "# text\n\n",
                    }
                    
                    

Example 8.10-8.13 :   Flow version is missing trailing backslash on first bullet line.
                The Block version of 8.12 & 8.13 is missing a final 's' on the final bulleted line
                
                I propose changing the left hand side on 8.12 & 8.13 to match 8.10, like this:
                    >

                     folded
                     line

                     next
                     line
                       * bullet

                       * list
                       * lines

                     last
                     line

                    # Comment                

                I propose changing the right hand side of all four to read:
                    %YAML 1.2
                    ---
                    !!str "\n\
                          folded line\n\
                          next line\n\
                          \  * bullet\n\
                          \n\
                          \  * list\n\
                          \  * lines\n\
                          \n\
                          last line\n"


Example 8.15:   Flow version missing a comma in inner sequence.
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!null "",
                      !!str "block node\n",
                      !!seq [
                        !!str "one",
                        !!str "two",
                      ],
                      !!map {
                        ? !!str "one"
                        : !!str "two",
                      },
                    ]
                    
Example 8.19:   Flow version has an extra comma on line 11.   In my parser, 
                this generates an extra unexpected !!null : !!null mapping
                entry at that point in the parse (is that right?!?)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!map {
                         !!str "sun" : !!str "yellow",
                      },
                      !!map {
                        ? !!map {
                          ? !!str "earth"
                          : !!str "blue"
                        }
                        : !!map {
                          ? !!str "moon"
                          : !!str "white"
                        },
                      }
                    ]

Example 8.21:   Flow version of folded and literal missing normalized newlines.   
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "literal"
                      : !!str "value\n",
                      ? !!str "folded"
                      : !<!foo> "value\n",
                    }                                    
                    
Example 9.3:    Block version - Comments not permitted in literals.

                I propose changing the _left_ hand side to read:
                
                    Bare
                    document
                    ...
                    # No document
                    ...
                    |
                    %!PS-Adobe-2.0
                    ...  #Looked like a directive, but the first line

                Flow version - Missing end-of-document indicator before 
                2nd YAML directive.   
                
                I propose changing the right  hand side to read:

                    %YAML 1.2
                    ---
                    !!str "Bare document"
                    ...
                    %YAML 1.2
                    ---
                    !!str "%!PS-Adobe-2.0\n"
                
                

Example 9.5:    Missing space in second YAML directive.
                
                I propose changing the _left_ hand side to read:
                    %YAML 1.2
                    --- |
                    %!PS-Adobe-2.0
                    ...
                    %YAML 1.2
                    ---
                    # Empty
                    ...
                
---  # YAML 1.1 # Old Specification issues: may be out of date
Example 9.1:   Trailing brace needs to be indented.
Example 9.7:   Trailing brace needs to be indented.
Example 9.12:  Output has extra second commas in "Up, up, and away"
Example 9.13:  Trailing brace needs to be indented.
Example 9.15:  How are content that looks like document indicators made safe?
Example 9.20:  Why doesn't tab (leading whitespace) counting a spaced line, 
               preserve the newline after it?
Example 9.23:  Shouldn't the PS in the "strip:" literal be reflected on output?
               Looks like it's been removed in 1.2 nearly identical example 8.5.
Example 10.7:  Does the empty key line needs a comma?
Example 10.7:  Does the line starting with "simple key" needs a comma?

Updated Wiki: Yaml_Specification_Issues

BurtHarris — Wed, 09 Dec 2009 19:17:45 GMT

%YAML 1.2
--- 
Title:          YAML 1.2 problems/fixes with examples specification

Based on:       http://yaml.org/spec/1.2/spec.html (3rd Edition, Patched at 2009-10-01)

Author:         Burt Harris

Summary:        The new YAML 1.2 specification is great.   I've been using the 
                examples as part of my unit testing, and discovered a few
                small corrections I believe should be made.   These all seem 
                to be typos rather than any sort of change in the meaning of 
                the spec.

Example 5.11:   Examples differ in two places by letter case on word "Line".
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!str "Line break (no glyph)\n\
                          Line break (glyphed)\n"

Example 5.12:   For consistency, right hand side needs two !!str tags.

                I propose changing the right hand side to read:

                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "quoted"
                      : !!str "Quoted \t",
                      ? !!str "block"
                      : !!str "void main() {\n\
                        \tprintf(\"Hello, world!\\n\");\n\
                        }\n",
                    }

                
Example 6.22:   Flow version isn't a sequence, doesn't match block version.
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                        !<tag:example.com,2000:app/foo> "bar"
                        ]

Example 6.23:   Perhaps it's intended to prove a point, but there
                seem to be gratuitous differences between left and 
                right hand version of this (e.g. number of anchors.)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ?  !!str &B1 "foo"
                      :  !!str "bar",
                      ?  !!str &B2 "baz"
                      :  *B1,
                    }

Example 7.1:    Map entries unnecessarily out-of-order (confusing.)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "First occurrence"
                      : &A !!str "Foo",
                      ? !!str "Second occurrence"
                      : *A,
                      ? !!str "Override anchor"
                      : &B !!str "Bar",
                      ? !!str "Reuse anchor"
                      : *B,
                    }

Example 7.10:   Extra comma in "Up, up, and away".
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!str "::vector",
                      !!str ": - ()",
                      !!str "Up, up, and away!",
                      !!int "-123",
                      !!str "http://example.com/foo#bar",
                      !!seq [
                        !!str "::vector",
                        !!str ": - ()",
                        !!str "Up, up and away!",
                        !!int "-123",
                        !!str "http://example.com/foo#bar",
                      ],
                    ]

Example 8.2:    Should newline after tab be preserved rather than folded?
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!str "detected\n",
                      !!str "\n\n# detected\n",
                      !!str " explicit\n",
                      !!str "\t\ndetected\n",
                    ]
                                    

Example 8.5:    Block version contains a double-down-arrow glyph, no longer a break 1.2.
                I propose changing the left hand side to read:
                
                    ·# Strip↓
                    ··# Comments:↓
                    strip: |-↓
                    ··# text↓
                    ··↓
                    ·# Clip↓
                    ··# comments:↓
                    ↓
                    clip: |↓
                    ··# text↓
                    ·↓
                    ·# Keep↓
                    ··# comments:↓
                    ↓
                    keep: |+↓
                    ··# text↓
                    ↓
                    ·# Trail↓
                    ··# comments.↓
                
                Also, should the last scalar in the flow version have one or two newlines?
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "strip"
                      : !!str "# text",
                      ? !!str "clip"
                      : !!str "# text\n",
                      ? !!str "keep"
                      : !!str "# text\n\n",
                    }
                    

Example 8.10-8.13 :   Flow version is missing trailing backslash on first bullet line.
                The Block version of 8.12 & 8.13 is missing a final 's' on the final bulleted line
                
                I propose changing the left hand side on 8.12 & 8.13 to match 8.10, like this:
                    >

                     folded
                     line

                     next
                     line
                       * bullet

                       * list
                       * lines

                     last
                     line

                    # Comment                

                I propose changing the right hand side of all four to read:
                    %YAML 1.2
                    ---
                    !!str "\n\
                          folded line\n\
                          next line\n\
                          \  * bullet\n\
                          \n\
                          \  * list\n\
                          \  * lines\n\
                          \n\
                          last line\n"


Example 8.15:   Flow version missing a comma in inner sequence.
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!null "",
                      !!str "block node\n",
                      !!seq [
                        !!str "one",
                        !!str "two",
                      ],
                      !!map {
                        ? !!str "one"
                        : !!str "two",
                      },
                    ]
                    
Example 8.19:   Flow version has an extra comma on line 11.   In my parser, 
                this generates an extra unexpected !!null : !!null mapping
                entry at that point in the parse (is that right?!?)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!map {
                         !!str "sun" : !!str "yellow",
                      },
                      !!map {
                        ? !!map {
                          ? !!str "earth"
                          : !!str "blue"
                        }
                        : !!map {
                          ? !!str "moon"
                          : !!str "white"
                        },
                      }
                    ]

Example 8.21:   Flow version of folded and literal missing normalized newlines.   
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "literal"
                      : !!str "value\n",
                      ? !!str "folded"
                      : !<!foo> "value\n",
                    }                                    
                    
Example 9.5:    Missing space in second YAML directive.
                
                I propose changing the _left_ hand side to read:
                    %YAML 1.2
                    --- |
                    %!PS-Adobe-2.0
                    ...
                    %YAML 1.2
                    ---
                    # Empty
                    ...
                
---  # YAML 1.1 # Old Specification issues: may be out of date
Example 9.1:   Trailing brace needs to be indented.
Example 9.7:   Trailing brace needs to be indented.
Example 9.12:  Output has extra second commas in "Up, up, and away"
Example 9.13:  Trailing brace needs to be indented.
Example 9.15:  How are content that looks like document indicators made safe?
Example 9.20:  Why doesn't tab (leading whitespace) counting a spaced line, 
               preserve the newline after it?
Example 9.23:  Shouldn't the PS in the "strip:" literal be reflected on output?
               Looks like it's been removed in 1.2 nearly identical example 8.5.
Example 10.7:  Does the empty key line needs a comma?
Example 10.7:  Does the line starting with "simple key" needs a comma?