NAME
YAML::Dump - Dump stuff, (simplified) YAML style
VERSION
This document describes YAML::Dump version 1.84.
SYNOPSIS
use YAML::Dump qw< Dump >;
my $data = { ... };
say Dump $data
DESCRIPTION
This module allows you to generate a YAML representation of a data
structure, provided that:
* there are no circular references
* there are no objects or "weird" references, but see below
If you recognize most (not all) the constraints of YAML::Tiny you are
totally right, because most of the code in this module is taken from
there. There are two notable differences:
* booleans are supported, see "Booleans"
* you can provide your way of dumping objects by implementing
"dumper_for_unknown", see "Unsupported References".
Booleans
Booleans are recognized and rendered as either false and true
(unquoted), depending on their truthness. The following variants are
recognized:
* a reference to a purely integer scalar variable holding values 0 or
1. Dual-lived variables or other values will not work.
* JSON::PP::Boolean
* boolean
* JSON::XS::Boolean
* Types::Serialiaser::Boolean (although it should not be needed)
* Mojo::JSON::_Bool, for Mojolicious up to version 6.21 (it later
switched to JSON::PP::Boolean).
Unsupported References
When a reference that is neither a hash nor an array reference is
found, method "dumper_for_objects" is called. This method first tries
to figure out if the reference is one of the allowed "Booleans"
representations, then hands over to a method "dumper_for_unknown" (if
the class has one), then as a last resort it complains loudly dieing.
If you want to provide your own dumping functions, you can either
override "dumper_for_objects" (losing support for "Booleans"), or
provide your method "dumper_for_unknown". By default there is none, so
you can either derive a subclass from YAML::Dump, or monkey-patch it by
implementing the method directly:
sub YAML::Dump::dumper_for_unknown {
my ($self, $element, $line, $indent, $seen) = @_;
}
FUNCTIONS
Dump
my $string = Dump(@data_structures);
generate a YAML representation of @data_structures.
INDENT
my $string = INDENT;
the indentation as space characters. This is useful if you have to
generate indentation string with "dumper_for_unknown".
METHODS
dumper_for_objects
my @lines = $obj->dumper_for_objects($element, $line, $indent, $seen);
This method generates a representation for booleans or, as a fallback,
calls "dumper_for_unknown". If you override this you lose the
possibility of dumping booleans, you are probably looking for
"dumper_for_unknown".
dumper_for_unknown
my @stuff = $obj->dumper_for_unknown($element, $line, $indent, $seen);
This method is not really present, but is invoked if you provide one
(either in a subclass, or monkey-patching YAML::Dump, see "Unsupported
References"). This allows you to provide your own generating functions
for your classes, should you need to do this.
The method is provided the following positional parameters:
$element
the element to dump in YAML
$line
the line where the element will be put (starting). It can be one of
the following:
* an empty string, in case the object is at the root level
* a string starting with spaces and ending with a dash -: your
element is part of an array
* a string ending with a colon :: your element is the value of a
hash
If your dump is just on a single line, it's sufficient to pre-pend
the string representation with a space; otherwise, decide what you
want to do also taking into consideration $indent (see below) and
also taking into consideration that it is your responsibility to
output the $line anyway.
$indent
The indentation level, should you need it (e.g. for multi-line
dumps). To generate the indentation string, use "INDENT":
my $indentation_string = INDENT x $indent;
$seen
used to track circular references. Use this if your object contains
other references with the potential for a cycle of references. This
is how you can use it:
sub dumper_for_unknown {
# ...
my $id = Scalar::Util::refaddr($some_reference);
die \'circular references are unsupported' if $seen->{$id};
# ...
}
The return value from this method can be either a list of lines (with
the proper indentation, and starting with the content of $line above)
or a single array or hash reference, which will be transformed
automatically. This allows you to basically ignore $line, $indent (but
probably not $seen) and let YAML::Dump do the work for you.
new
my $obj = YAML::Dump->new(@data_for_dumping);
Generate an object. You should not need to use this, use "Dump"
instead.
BUGS AND LIMITATIONS
Report bugs through GitHub (patches welcome).
SEE ALSO
YAML::Tiny, where most of the code was taken. But hey! There is also my
stuff!
AUTHOR
Flavio Poletti
COPYRIGHT AND LICENSE
This is tricky. A good part of the code comes from YAML::Tiny, whose
copyright statement at time of copy is:
Copyright 2006 - 2013 Adam Kennedy.
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
Now, under the same terms as Perl itself is in itself a bit ambiguous,
even though the original LICENSE has this:
This software is copyright (c) 2006 by Adam Kennedy.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
Terms of the Perl programming language system itself
a) the GNU General Public License as published by the Free
Software Foundation; either version 1, or (at your option) any
later version, or b) the "Artistic License"
Again, it's my understanding that even the same terms as Perl 5
programming language system itself is a bit ambiguous. Also, the
Artistic License is, in itself, ambiguous, which is why the Perl
Foundation eventually recommended the Artistic License 2.0.
Anyway, a hopefully compatible license can be found in file LICENSE.
Additions are copyright (C) 2018 by Flavio Poletti
This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.