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.