=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.42.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 NAME

YAML::XS - Perl YAML Serialization using XS and libyaml

=for html
<a href="https://travis-ci.org/ingydotnet/yaml-libyaml-pm"><img src="https://travis-ci.org/ingydotnet/yaml-libyaml-pm.png" alt="yaml-libyaml-pm"></a>

=head1 SYNOPSIS

    use YAML::XS;

    my $yaml = Dump [ 1..4 ];
    my $array = Load $yaml;

    my $yaml = DumpFile ("my.yml", [ 1..4 ]);
    my $array = LoadFile "my.yml";

=head1 DESCRIPTION

Kirill Siminov's C<libyaml> is a good YAML library implementation. The C
library is written precisely to the YAML 1.1 specification, and offers YAML
1.2 support. It was originally bound to Python and was later bound to Ruby.
C<libsyck> is written a bit more elegant, has less bugs, is not as strict as
libyaml, but misses some YAML features. It can only do YAML 1.1

This module is a Perl XS binding to libyaml which offers Perl somewhat
acceptable YAML support to date.

This module exports the functions C<Dump>, C<Load>, C<DumpFile> and
C<LoadFile>. These functions are intended to work exactly like C<YAML.pm>'s
corresponding functions.

If you set the option C<$YAML::XS::IndentlessMap> to 0 or undef, C<YAML::XS>
will behave like with version E<lt> 0.70, which creates yml files which cannot
be read by C<YAML.pm>

However the loader is stricter than C<YAML>, C<YAML::Syck> and
C<CPAN::Meta::YAML> i.e. C<YAML::Tiny> as used in core. Set the variable
C<$YAML::XS::NonStrict> to allow certain reader errors to pass the
C<CPAN::Meta> validation testsuite.

=head1 CONFIGURATION

=head2 Loader Options

via globals variables only, so far. Affecting Load and LoadFile.

-- C<$YAML::XS::NonStrict>

Permit certain reader errors to loosely match other YAML module semantics. In
detail: Allow C<"control characters are not allowed">. Note that any error is
stored and returned, just not immediately.

However the reader error C<"invalid trailing UTF-8 octet"> and all other utf8
strictness violations are still fatal.

And if the structure of the YAML document cannot be parsed, i.e. a required
value consists only of invalid control characters, the loader returns an
error, unlike with non-strict YAML modules.

-- C<$YAML::XS::LoadCode>

Ignored. If enabled supports deparsing and evaling of code blocks.

=head2 Dumper Options

via globals variables only, so far. Affecting Dump and DumpFile

-- C<$YAML::XS::UseCode>

If enabled supports Dump of CV code blocks via C<YAML::XS::coderef2text()>.

-- C<$YAML::XS::DumpCode>

If enabled supports Dump of CV code blocks via C<YAML::XS::coderef2text()>.

-- C<$YAML::XS::QuoteNumericStrings>

When true (the default) strings that look like numbers but have not been
numified will be quoted when dumping.

This ensures leading that things like leading zeros and other formatting are
preserved.

-- C<$YAML::XS::IndentlessMap>

Default 0

Set to 1 or a true value to fallback to the old C<YAML::XS> behavior to omit
the indentation of map keys, which arguably violates the YAML spec, is
different to all other YAML libraries and causes C<YAML.pm> to fail.

With 0

     authors:
       - this author

With 1

     authors:
     - this author

-- C<$YAML::XS::Indent>

Default 2

-- C<$YAML::XS::BestWidth>

Default 80

Control text wrapping.

-- C<$YAML::XS::Canonical>

Default 1

Set to undef or 0 to disable sorting map keys.

-- C<$YAML::XS::Unicode>

Default 1

Set to undef or 0 to disallow unescaped non-ASCII characters.

-- C<$YAML::XS::Encoding>

Default utf8

Set to any, utf8, utf16le or utf16be

-- C<$YAML::XS::LineBreak>

Default ln

Set to any, cr, ln or crln.

-- C<$YAML::XS::OpenEnded>

Default 0

Set to 1 or a true value to embed the yaml into "...". If an explicit document
end is required.

=head1 USING YAML::XS WITH UNICODE

Handling unicode properly in Perl can be a pain. YAML::XS only deals with
streams of utf8 octets. Just remember this:

    $perl = Load($utf8_octets);
    $utf8_octets = Dump($perl);

There are many, many places where things can go wrong with unicode. If you are
having problems, use Devel::Peek on all the possible data points.

=head1 SEE ALSO

=over

=item * YAML.pm

=item * YAML::Syck

=item * YAML::Tiny

=item * CPAN::Meta::YAML

=back

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright 2007-2016. Ingy döt Net.

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
