NAME
    YAML::Tiny - Read/Write YAML files with as little code as possible

PREAMBLE
    The YAML specification is huge. Really, really huge. It contains all the
    functionality of XML, except with flexibility and choice, which makes it
    easier to read, but with a formal specification that is more complex
    than XML.

    The original pure-Perl implementation YAML costs just over 4 megabytes
    of memory to load. Just like with Windows .ini files (3 meg to load) and
    CSS (3.5 meg to load) the situation is just asking for a YAML::Tiny
    module, an incomplete but correct and usable subset of the
    functionality, in as little code as possible.

    Like the other "::Tiny" modules, YAML::Tiny will have no non-core
    dependencies, not require a compiler, and be back-compatible to at least
    perl 5.005_03, and ideally 5.004.

SYNOPSIS
        #############################################
        # In your file
    
        ---
        rootproperty: blah
        section:
          one: two
          three: four
          Foo: Bar
          empty: ~
    
        #############################################
        # In your program
    
        use YAML::Tiny;
    
        # Create a YAML file
        my $yaml = YAML::Tiny->new;
    
        # Open the config
        $yaml = YAML::Tiny->read( 'file.yml' );
    
        # Reading properties
        my $root = $yaml->[0]->{rootproperty};
        my $one  = $yaml->[0]->{section}->{one};
        my $Foo  = $yaml->[0]->{section}->{Foo};
    
        # Changing data
        $yaml->[0]->{newsection} = { this => 'that' }; # Add a section
        $yaml->[0]->{section}->{Foo} = 'Not Bar!';     # Change a value
        delete $yaml->[0]->{section};                  # Delete a value or section
    
        # Add an entire document
        $yaml->[1] = [ 'foo', 'bar', 'baz' ];
    
        # Save the file
        $yaml->write( 'file.conf' );

DESCRIPTION
    YAML::Tiny is a perl class for reading and writing YAML-style files,
    written with as little code as possible, reducing load time and memory
    overhead.

    Most of the time it is accepted that Perl applications use a lot of
    memory and modules. The ::Tiny family of modules is specifically
    intended to provide an ultralight and zero-dependency alternative to
    many more-thorough standard modules.

    This module is primarily for reading human-written files (like simple
    config files) and generating very simple human-readable files. Note that
    I said human-readable and not geek-readable. The sort of files that your
    average manager or secretary should be able to look at and make sense
    of.

    YAML::Tiny does not generate comments, it won't necesarily preserve the
    order of your hashes, and it will normalise if reading in and writing
    out again.

    It only supports a very basic subset of the full YAML specification.

    Usage is targetted at files like Perl's META.yml, for which a small and
    easily-embeddable module is extremely attractive.

    Features will only be added if they are human readable, and can be
    written in a few lines of code. Please don't be offended if your request
    is refused. Someone has to draw the line, and for YAML::Tiny that
    someone is me.

    If you need something with more power move up to YAML (4 megabytes of
    memory overhead) or YAML::Syck (275k, but requires libsyck and a C
    compiler).

    To restate, YAML::Tiny does not preserve your comments, whitespace, or
    the order of your YAML data. But it should round-trip from Perl
    structure to file and back again just fine.

METHODS
  new
    The constructor "new" creates and returns an empty "YAML::Tiny" object.

  read $filename
    The "read" constructor reads a YAML file, and returns a new "YAML::Tiny"
    object containing the contents of the file.

    Returns the object on success, or "undef" on error.

    When "read" fails, "YAML::Tiny" sets an error message internally you can
    recover via "YAML::Tiny->errstr". Although in some cases a failed "read"
    will also set the operating system error variable $!, not all errors do
    and you should not rely on using the $! variable.

  read_string $string;
    The "read_string" method takes as argument the contents of a YAML file
    (a YAML document) as a string and returns the "YAML::Tiny" object for
    it.

  write $filename
    The "write" method generates the file content for the properties, and
    writes it to disk to the filename specified.

    Returns true on success or "undef" on error.

  write_string
    Generates the file content for the object and returns it as a string.

  errstr
    When an error occurs, you can retrieve the error message either from the
    $YAML::Tiny::errstr variable, or using the "errstr()" method.

FUNCTIONS
    YAML::Tiny implements a number of functions to add compatibility with
    the YAML API. These should be a drop-in replacement, except that
    YAML::Tiny will not export functions by default, and so you will need to
    explicitly import the functions.

  Dump
      my $string = Dump(list-of-Perl-data-structures);

    Turn Perl data into YAML. This function works very much like
    Data::Dumper::Dumper().

    It takes a list of Perl data strucures and dumps them into a serialized
    form.

    It returns a string containing the YAML stream.

    The structures can be references or plain scalars.

  Load
      my @documents = Load(string-containing-a-YAML-stream);

    Turn YAML into Perl data. This is the opposite of Dump.

    Just like Storable's thaw() function or the eval() function in relation
    to Data::Dumper.

    It parses a string containing a valid YAML stream into a list of Perl
    data structures.

  freeze() and thaw()
    Aliases to Dump() and Load() for Storable fans. This will also allow
    YAML::Tiny to be plugged directly into modules like POE.pm, that use the
    freeze/thaw API for internal serialization.

  DumpFile(filepath, list)
    Writes the YAML stream to a file instead of just returning a string.

  LoadFile(filepath)
    Reads the YAML stream from a file instead of a string.

SUPPORT
    Bugs should be reported via the CPAN bug tracker at

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-Tiny>

AUTHOR
    Adam Kennedy <adamk@cpan.org>

SEE ALSO
    YAML, YAML::Syck, Config::Tiny, CSS::Tiny,
    <http://use.perl.org/~Alias/journal/29427>, <http://ali.as/>

COPYRIGHT
    Copyright 2006 - 2007 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.

