NAME
YAML::XS - Perl YAML Serialization using XS and libyaml
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";
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.
-- $YAML::XS::NonStrict
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.
-- $YAML::XS::LoadCode
Ignored. If enabled supports deparsing and evaling of code blocks.
Dumper Options
via globals variables only, so far. Affecting Dump and DumpFile
-- $YAML::XS::UseCode
If enabled supports Dump of CV code blocks via
YAML::XS::coderef2text().
-- $YAML::XS::DumpCode
If enabled supports Dump of CV code blocks via
YAML::XS::coderef2text().
-- $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.
-- $YAML::XS::IndentlessMap
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
-- $YAML::XS::Indent
Default 2
-- $YAML::XS::BestWidth
Default 80
Control text wrapping.
-- $YAML::XS::Canonical
Default 1
Set to undef or 0 to disable sorting map keys.
-- $YAML::XS::Unicode
Default 1
Set to undef or 0 to disallow unescaped non-ASCII characters.
-- $YAML::XS::Encoding
Default utf8
Set to any, utf8, utf16le or utf16be
-- $YAML::XS::LineBreak
Default ln
Set to any, cr, ln or crln.
-- $YAML::XS::OpenEnded
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
* YAML.pm
* YAML::Syck
* YAML::Tiny
* CPAN::Meta::YAML
AUTHOR
Ingy döt Net <ingy@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