NAME

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

VERSION

Version 0.50_07

SYNOPSIS

    #############################################
    # In your file
    
    ---
    rootproperty: blah
    section:
      one: two
      three: four
      Foo: Bar
      empty: ~
    
    
    
    #############################################
    # In your program
    
    use TAPx::Parser::YAML;
    
    # Create a YAML file
    my $yaml = TAPx::Parser::YAML->new;
    
    # Open the config
    $yaml = TAPx::Parser::YAML->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

Note that this code is lifted directly from YAML::Tiny and used with the permission of Adam Kennedy.

TAPx::Parser::YAML 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.

TAPx::Parser::YAML 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 TAPx::Parser::YAML 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, TAPx::Parser::YAML 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 TAPx::Parser::YAML object.

read $filename

The read constructor reads a YAML file, and returns a new TAPx::Parser::YAML object containing the contents of the file.

Returns the object on success, or undef on error.

When read fails, TAPx::Parser::YAML sets an error message internally you can recover via TAPx::Parser::YAML->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 TAPx::Parser::YAML 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 $TAPx::Parser::YAML::errstr variable, or using the errstr() method.

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 TAPx::Parser

perl -MCPAN -e shell
install TAPx::Parser