NAME

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

yaml-libyaml-pm

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";

    { # security, disable custom tags
      local $YAML::XS::DisableBlessed = 1;
      my $array = LoadFile("META.yml");
    }

DESCRIPTION

Kirill Siminov's 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. 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 Dump, Load, DumpFile and LoadFile. These functions are intended to work exactly like YAML.pm's corresponding functions.

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

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

CONFIGURATION

Loader Options

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

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

However the reader error "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.

Not yet implemented. Disables support for deparsing and evaling of code blocks while loading.

Disables support for blessing custom tags while loading, but allows pure perl tags, such as array, hash and scalar.

Dumper Options

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

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

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

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.

Default 0

Set to 1 or a true value to fallback to the old 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 YAML.pm to fail.

With 0

     authors:
       - this author

With 1

     authors:
     - this author

Default 2

Default 80

Control text wrapping.

Default 1

Set to undef or 0 to disable sorting map keys.

Default 1

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

Default utf8

Set to any, utf8, utf16le or utf16be

Default ln

Set to any, cr, ln or crln.

Default 0

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

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.

SEE ALSO

AUTHOR

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

Reini Urban <rurban@cpan.org>

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 http://www.perl.com/perl/misc/Artistic.html