Name
YAML::Safe - Safe Perl YAML Serialization using XS and libyaml
Synopsis
use YAML::Safe qw(LoadFile DumpFile);
my $yaml = Dump [ 1..4 ];
my $array = Load $yaml;
$yaml = DumpFile ("my.yml", [ 1..4 ]);
$array = LoadFile "my.yml";
open my $fh, "my.yml";
$yaml = DumpFile ($fh, [ 1..4 ]);
$array = LoadFile $fh;
open *FH, "my.yml";
$yaml = DumpFile (*FH, [ 1..4 ]);
$array = LoadFile *FH;
my $obj = YAML::Safe->new;
$yaml = $obj->DumpFile ("my.yml", [ 1..4 ]);
$array = $obj->LoadFile("my.yml");
$yaml = YAML::Safe->new->nonstrict->encoding("any");
$yaml->SafeClass("DateTime");
$array = $yaml->SafeLoadFile("META.yml");
$yaml = YAML::Safe->new->canonical;
$yaml->SafeClass("DateTime");
$array = $yaml->SafeDumpFile("META.yml");
Description
This module is a re-factoring of YAML::XS, the old Perl XS binding to
"libyaml" which offers Perl somewhat acceptable YAML support to date.
YAML::XS never produced code which could be read from YAML, and thus was
unsuitable to be used as YAML replacement for core and CPAN. It also
required reading and setting options from global variables.
Kirill Siminov's "libyaml" is a 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.0.
This module exports the functions "Dump" and "Load", and do work as
functions exactly like YAML::XS and "YAML.pm"'s corresponding functions.
It is however preferred to use the new OO-interface to store all options
in the new created object. YAML::Safe does not support the old globals
anymore.
There are also new Safe variants of Load and Dump methods, and options
as setter methods. With the Safe methods you can enforce loading YAML
1.0 files only, all unsafe tags are removed. By default all blessed data
is unsafe.
If you set the option "noindentmap", "YAML::Safe" 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 option
"nonstrict" to allow certain reader errors to pass the "CPAN::Meta"
validation testsuite.
FUNCTIONS
Load
LoadFile
Dump
DumpFile
libyaml_version
METHODS
new "classname", option => value, ...
Create a YAML loader or dumper object with some options.
SafeClass "classname", ...
Register a string or list of strings to the list of allowed classes
to the "Safe{Load,Dump}" methods. Without any SafeClass added, no
custom "!" classes are allow in the YAML. Regexp are not supported.
SafeLoad
SafeLoadFile
Restrict the loader to the registered safe classes only or tags
starting with "perl/".
SafeDump
SafeDumpFile
Restrict the dumper to the registered safe classes only or tags
starting with "perl/".
And all the loader and dumper options as getter and setter methods. See
below.
Configuration
Options for Loader and Dumper
via getter and setter methods.
"enablecode" =item "get_enablecode"
If enabled turns on handling of code blocks for the loader and
dumper. It sets both the "loadcode" and "dumpcode" option.
"disableblessed" =item "get_disableblessed"
Default 0
If set, i.e. blessed is disabled, all blessed data for the Loader
and Dumper is unblessed. This is similar to the Safe methods without
any SafeClass set.
"encoding" =item "get_encoding"
Default "utf8"
Set to "any", "utf8", "utf16le" or "utf16be".
"boolean" =item "get_boolean"
Set to "JSON::PP" or "boolean" to enable or 0 to disable. Encodes
true and false to the respective classes. It will try to load
JSON::PP or boolean and die if it can't be loaded.
With that it's possible to add new "real" booleans to a data
structure:
my $o = YAML::Safe->new->boolean("JSON::PP"); # or "boolean"
my $data = $o->Load("booltrue: true");
$data->{boolfalse} = JSON::PP::false;
my $yaml = Dump($data);
# boolfalse: false
# booltrue: true
Please note that JSON::PP::Boolean and boolean.pm behave a bit
differently. Ideally you should only use them in boolean context.
Setting a boolean() class is only possible on a perl since v5.8.9.
It will die on older perls.
If not set, booleans are loaded as special perl variables
"PL_sv_yes" and "PL_sv_no", which have the disadvantage that they
are readonly, and you can't add those to an existing data structure
with pure perl.
If you simply need to load "perl booleans" that are true or false in
boolean context, you will be fine with the default setting.
"safemode" =item "get_safemode"
Default 0
If enabled by using the the Safe methods restrict the blessing only
for the set of registered classes or tags starting with "perl/".
Loader Options
via getter and setter methods.
"nonstrict" =item "get_nonstrict"
If enabled permits certain reader errors to loosely match other YAML
module semantics. In detail: Allow "control characters are not
allowed" with while parsing a quoted scalar found unknown escape
character. Note that any error is stored and returned, just not
immediately. This is needed for cpan distroprefs.
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.
"loadcode" =item "get_loadcode"
Turns on deparsing and evaling of code blocks in the loader.
Dumper Options
via globals variables or as optional getter and setter methods.
"dumpcode" =item "get_dumpcode"
If enabled supports Dump of CV code blocks via
YAML::Safe::coderef2text().
"quotenum" =item "get_quotenum"
Default: enabled.
If enabled 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.
"noindentmap" =item "get_noindentmap"
If enabled fallback to the old "YAML::Safe" behavior to omit the
indentation of map keys, which arguably violates the first YAML spec
(<https://yaml.org/spec/1.0/#id2566128>), is different to most other
YAML libraries and causes older "YAML.pm" to fail.
Disabled
authors:
- this author
Enabled
authors:
- this author
"indent" =item "get_indent"
Default 2. Valid values are from 1 - 10.
"wrapwidth" =item "get_wrapwidth"
Default 80
Control text wrapping.
"canonical" =item "get_canonical"
Default: disabled.
Enable to sort map keys.
"unicode" =item "get_unicode"
Default 1
Set to undef or 0 to disallow unescaped non-ASCII characters. e.g.
"YAML::Safe-"new->unicode(0)>
"linebreak" =item "get_linebreak"
Default ln
Set to "any", "cr", "ln" or "crln".
"openended" =item "get_openended"
Default 0
If enabled embed the yaml into "...", if an explicit document end is
required.
Using YAML::Safe with Unicode
Handling unicode properly in Perl can be a pain. YAML::Safe 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::XS
YAML::Syck
YAML::Tiny
CPAN::Meta::YAML
Author
Reini Urban <rurban@cpan.org>, based on YAML::XS by Ingy döt Net
<ingy@cpan.org>
Copyright and License
Copyright 2007-2016. Ingy döt Net. Copyright 2015-2019. Reini Urban.
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>