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 (), 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 , based on YAML::XS by Ingy döt Net 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