WIP

lib/YAML/PP.pm

@@ -437,8 +437,8 @@ Here are a few examples of the basic load and dump methods:
     my $yaml = $ypp->dump_string($data1, $data2);
     $ypp->dump_file($filename, $data1, $data2);
 
-    # The loader offers JSON::PP::Boolean, boolean.pm or
-    # perl 1/'' (currently default) for booleans
+    # The loader offers JSON::PP::Boolean, boolean.pm,
+    # perl 1/'' (currently default) or C<perl_experimental> for booleans
     my $ypp = YAML::PP->new(boolean => 'JSON::PP');
     my $ypp = YAML::PP->new(boolean => 'boolean');
     my $ypp = YAML::PP->new(boolean => 'perl');
@@ -1132,7 +1132,7 @@ This is supported since 0.029 (except some not relevant cases):
     ---
     key ends with two colons::: value
 
-This was added in 0.037
+This was implemented in 0.037.
 
 =item Supported Characters
 
@@ -1292,6 +1292,87 @@ The layout is like libyaml output:
 
 Yes, this can be enabled optionally, see L<YAML::PP::Schema::Merge>
 
+=item Is there a linter / formatter for YAML
+
+There is the widely L<"yamllint"|https://yamllint.readthedocs.io/>, based on
+python's PyYAML. It is very configurable and will report errors or warnings.
+It cannot format.
+
+Now there is also L<YAML::Tidy>, which will format the given file according
+to your configuration. So far only a few configuration options exist, but
+they can already be quite helpful.
+
+=back
+
+=head1 Which YAML module should I use?
+
+There are many YAML modules on CPAN. For historical reasons some of them
+aren't handling YAML correctly.
+
+Most of them are not compatible with YAML and with each other, meaning they can
+interpret the same YAML differently.
+
+The behaviours we are discussing here can be divided into parsing issues
+(syntax) and loading/constructing issues (for example type resolving which
+decides what is a number, boolean or null).
+
+See also L<https://matrix.yaml.info/> (parsing) and
+L<https://perlpunk.github.io/YAML-PP-p5/schema-examples.html> (loading).
+
+=over
+
+=item L<"YAML.pm"|YAML>
+
+It was written even before the YAML 1.0 spec was finished and by that enabled
+perl users to process YAML very early. It might work for you if you have simple
+data, but it's missing quite some features and can also produce YAML that
+doesn't roundtrip. Nowadays it might be a good idea to switch.
+
+=item L<YAML::XS>
+
+A libyaml binding that is robust and widely used. However, there are two
+things to consider.
+
+1. libyaml diverged from the spec in several aspects. They are rare though.
+2. The type resolving does not adhere to YAML 1.1 or YAML 1.2, meaning it is
+   incompatible with other YAML libraries in perl or other languages.
+
+=item L<YAML::Tiny>
+
+It implements both a tiny subset of YAML, but also a superset. Meaning
+it will happily accept some YAML documents that are not officially valid.
+Type resolving is also not implemented according to the spec.
+
+=item L<YAML::Syck>
+
+A binding to libsyck. It is even less compatible to YAML than libyaml. Also
+type resolving is not implemented according to the spec.
+
+=item L<YAML::PP>
+
+Regarding YAML syntax, it is the second most YAML 1.2 compatible perl module.
+The cases it cannot (yet) parse are not relevant in perl programming,
+e.g. hash keys that are not strings.
+Regarding type resolving, it is compatible with the YAML 1.2 Core schema,
+so it should be possible to exchange data as YAML with other libraries
+in other languages.
+One downside is that it is the slowest perl YAML module.
+
+=item L<YAML::Parser>
+
+This is a parser generated by the YAML grammar, and it's passing all
+official tests. A L<YAML::PP::Ref> frontend exists that you can use just like
+YAML::PP.
+It is quite slow (although it might be ok for small files depending on the
+use case).
+The error messages it creates on invalid YAML are not helpful currently.
+
+=item L<YAML::PP::LibYAML>
+
+This combines the L<YAML::LibYAML::API> binding for parsing with the YAML::PP
+frontend for loading and type resolving.
+It is faster than YAML::PP but slower than YAML::XS.
+
 =back
 
 =head1 WHY
@@ -1341,10 +1422,6 @@ 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.
 
@@ -1409,7 +1486,9 @@ Felix answered countless questions about the YAML Specification.
 
 =item L<YAML::LibYAML::API>
 
-=item L<https://www.yaml.info>
+=item L<YAML::Tidy>
+
+=item L<https://www.yaml.info/>
 
 =back
 

xt/03.spelling.t

@@ -11,29 +11,31 @@ all_pod_files_spelling_ok( qw( bin lib ) );
 
 __DATA__
 ansi
+dumpcode
+DumpFile
 failsafe
 FUNCTIONS
+header
+loadcode
+libsyck
+libyaml
 LoadFile
+Nim
 RAML
-Schema
-Schemas
-dumpcode
-loadcode
 refref
+Representer
+roundtrip
 scalarref
-yaml
-DumpFile
-Nim
-libyaml
-vimscript
-unicode
-tml
 schemas
-Representer
-TestML
-USD
-header
+Schema
+Schemas
+superset
+tml
 TODO
+unicode
+USD
+vimscript
+yaml
 Ingy
 döt
 Net