NAME

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

PREAMBLE

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

The 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 to read and write YAML-style files 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 the standard modules.

This module is primarily for reading human-written files (like 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 would be highly useful.

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

SUPPORT

Bugs should be reported via the CPAN bug tracker at

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

For other issues, or commercial enhancement or support, please contact Adam Kennedy directly.

AUTHOR

Adam Kennedy <adamk@cpan.org>

SEE ALSO

YAML, YAML::Syck, Config::Tiny, CSS::Tiny, http://use.perl.org/~Alias/journal/29427

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.

cpanm YAML::Tiny

perl -MCPAN -e shell
install YAML::Tiny