/ 
YAML-Dump-1.84
River stage zero No dependents
/ YAML::Dump

NAME

YAML::Dump - Dump stuff, (simplified) YAML style

VERSION

This document describes YAML::Dump version 1.84.

Build Status Perl Version Current CPAN version Kwalitee CPAN Testers CPAN Testers Matrix

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

Booleans are recognized and rendered as either false and true (unquoted), depending on their truthness. The following variants are recognized:

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 <polettix@cpan.org>

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 <polettix@cpan.org>

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.