NAME

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

VERSION

    This document describes YAML::Dump version 1.82.

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 or 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.

