DESCRIPTION

YAML::PP is a modular YAML processor.

It aims to support YAML 1.2 and YAML 1.1. See http://yaml.org/. Some (rare) syntax elements are not yet supported and documented below.

YAML is a serialization language. The YAML input is called "YAML Stream". A stream consists of one or more "Documents", separated by a line with a document start marker ---. A document optionally ends with the document end marker ....

This allows one to process continuous streams additionally to a fixed input file or string.

The YAML::PP frontend will currently load all documents, and return only the first if called with scalar context.

The YAML backend is implemented in a modular way that allows one to add custom handling of YAML tags, perl objects and data types. The inner API is not yet stable. Suggestions welcome.

Like in modules like YAML, the Constructor will use references for mappings and sequences, but obviously not for scalars.

YAML::XS uses real aliases, which allows also aliasing scalars. I might add an option for that since aliasing is now available in pure perl.

Boolean Handling

You can choose between 'perl' (1/'', currently default), 'JSON::PP' and 'boolean'.pm for handling boolean types. That allows you to dump the data structure with one of the JSON modules without losing information about booleans.

Numbers

Numbers are created as real numbers instead of strings, so that they are dumped correctly by modules like JSON::PP or JSON::XS, for example.

Complex Keys

Mapping Keys in YAML can be more than just scalars. Of course, you can't load that into a native perl structure. The Constructor will stringify those keys with Data::Dumper instead of just returning something like HASH(0x55dc1b5d0178).

I would like to generate a complete parse tree, that allows you to manipulate the data structure and also dump it, including all whitespaces and comments. The spec says that this is throwaway content, but I read that many people wish to be able to keep the comments.

YAML::PP::Dumper, YAML::PP::Emitter

The Dumper should be able to dump strings correctly, adding quotes whenever a plain scalar would look like a special string, like true, or when it contains or starts with characters that are not allowed.

Most strings will be dumped as plain scalars without quotes. If they contain special characters or have a special meaning, they will be dumped with single quotes. If they contain control characters, including <"\n">, they will be dumped with double quotes.

It will recognize JSON::PP::Boolean and boolean.pm objects and dump them correctly.

Numbers which also have a PV flag will be recognized as numbers and not as strings:

my $int = 23;
say "int: $int"; # $int will now also have a PV flag

That means that if you accidentally use a string in numeric context, it will also be recognized as a number:

WHY

All the available parsers and loaders for Perl are behaving differently, and more important, aren't conforming to the spec. YAML::XS is doing pretty well, but libyaml only handles YAML 1.1 and diverges a bit from the spec. The pure perl loaders lack support for a number of features.

I was going over YAML.pm issues end of 2016, integrating old patches from rt.cpan.org and creating some pull requests myself. I realized that it would be difficult to patch YAML.pm to parse YAML 1.1 or even 1.2, and it would also break existing usages relying on the current behaviour.

YAML TEST SUITE

It contains about 230 test cases and expected parsing events and more. There will be more tests coming. This test suite allows you to write parsers without turning the examples from the Specification into tests yourself. Also the examples aren't completely covering all cases - the test suite aims to do that.

The suite contains .tml files, and in a separate 'data' release you will find the content in separate files, if you can't or don't want to use TestML.

Thanks also to Felix Krause, who is writing a YAML parser in Nim. He turned all the spec examples into test cases.

YAML EDITOR

This is a tool to play around with several YAML parsers and loaders in vim.

The project contains the code to build the frameworks (16 as of this writing) and put it into one big Docker image.

It also contains the yaml-editor itself, which will start a vim in the docker container. It uses a lot of funky vimscript that makes playing with it easy and useful. You can choose which frameworks you want to test and see the output in a grid of vim windows.

Especially when writing a parser it is extremely helpful to have all the test cases and be able to play around with your own examples to see how they are handled.

YAML TEST MATRIX

I was curious to see how the different frameworks handle the test cases, so, using the test suite and the docker image, I wrote some code that runs the tests, manipulates the output to compare it with the expected output, and created a matrix view.

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.