—package
YAML::Tiny;
# YAML, but just the best bits
use
5.004;
use
strict;
BEGIN {
$VERSION
=
'0.01'
;
$errstr
=
''
;
}
# Create the main error hash
my
%ERROR
= (
YAML_PARSE_ERR_NO_FINAL_NEWLINE
=>
"Stream does not end with newline character"
,
);
my
%NO
= (
'#'
=>
'YAML::Tiny does not support partial-line comments'
,
'%'
=>
'YAML::Tiny does not support directives'
,
'&'
=>
'YAML::Tiny does not support anchors'
,
'*'
=>
'YAML::Tiny does not support aliases'
,
'?'
=>
'YAML::Tiny does not support explicit mapping keys'
,
':'
=>
'YAML::Tiny does not support explicit mapping values'
,
'|'
=>
'YAML::Tiny does not support literal multi-line scalars'
,
'>'
=>
'YAML::Tiny does not support folded multi-line scalars'
,
'!'
=>
'YAML::Tiny does not support explicit tags'
,
"'"
=> 'YAML::Tiny does not support quoted strings',
'"'
=>
'YAML::Tiny does not support quoted strings'
,
);
# Create an empty YAML::Tiny object
sub
new {
bless
[],
shift
;
}
# Create an object from a file
sub
read
{
my
$class
=
ref
$_
[0] ?
ref
shift
:
shift
;
# Check the file
my
$file
=
shift
or
return
$class
->_error(
'You did not specify a file name'
);
return
$class
->_error(
"File '$file' does not exist"
)
unless
-e
$file
;
return
$class
->_error(
"'$file' is a directory, not a file"
)
unless
-f _;
return
$class
->_error(
"Insufficient permissions to read '$file'"
)
unless
-r _;
# Slurp in the file
local
$/ =
undef
;
open
CFG,
$file
or
return
$class
->_error(
"Failed to open file '$file': $!"
);
my
$contents
= <CFG>;
close
CFG;
$class
->read_string(
$contents
);
}
# Create an object from a string
sub
read_string {
my
$class
=
ref
$_
[0] ?
ref
shift
:
shift
;
my
$self
=
bless
[],
$class
;
# Handle special cases
return
undef
unless
defined
$_
[0];
return
$self
unless
length
$_
[0];
unless
(
$_
[0] =~ /[\012\015]+$/ ) {
return
$class
->_error(
'YAML_PARSE_ERR_NO_FINAL_NEWLINE'
);
}
# State variables
my
$line
= 0;
my
$state
= FILE;
my
$document
=
undef
;
my
@indents
= ( );
my
@cursors
= ( );
foreach
(
split
/(?:\015{1,2}\012|\015|\012)/,
shift
) {
$line
++;
# Skip comments and empty lines
next
if
/^\s*(?:\
#|$)/;
# Get the indent level for the line
my
$indent
= s/^(\s+)// ?
length
($1) : 0;
# Check for a document header
if
( s/^(---(?:\s+|\Z))// ) {
if
(
$state
== FILE ) {
$state
= START;
}
else
{
# Change to new document
push
@$self
,
$document
;
$document
=
undef
;
$state
= START;
}
next
unless
length
$_
;
my
$c
=
substr
(
$_
, 0, 1);
return
$class
->_error(
$NO
{
$c
})
if
$NO
{
$c
};
# Assume a scalar
$document
=
$self
->_read_scalar(
$_
);
next
;
}
# Are we in START mode, expecting a list or hash
if
(
$state
== START ) {
my
$c
=
substr
(
$_
,0,1);
return
$class
->_error(
$NO
{
$c
})
if
$NO
{
$c
};
if
( s/^(-(?:\s+|\Z))// ) {
# We have an ARRAY
$document
= [ ];
push
@indents
,
$indent
;
push
@cursors
,
$document
;
unless
(
length
$_
) {
# Open array
$state
= OPEN_ARRAY;
next
;
}
$c
=
substr
(
$_
, 0, 1);
return
$class
->_error(
$NO
{
$c
})
if
$NO
{
$c
};
# Assume a scalar
push
@$document
,
$self
->_read_scalar(
$_
);
$state
= ARRAY;
next
;
}
}
# Are we in ARRAY mode, expecting the next array element
if
(
$state
== ARRAY ) {
my
$c
=
substr
(
$_
,0,1);
return
$class
->_error(
$NO
{
$c
})
if
$NO
{
$c
};
if
( s/^(-(?:\s+|\Z))// ) {
# We have an ARRAY
### Assume for now we are at the same indent level
unless
(
length
$_
) {
# Open array
$state
= OPEN_ARRAY;
next
;
}
$c
=
substr
(
$_
, 0, 1);
return
$class
->_error(
$NO
{
$c
})
if
$NO
{
$c
};
# Assume a scalar
push
@$document
,
$self
->_read_scalar(
$_
);
next
;
}
}
die
"CODE INCOMPLETE"
;
}
# Save final document
push
@$self
,
$document
unless
$state
== FILE;
$self
;
}
# Deparse a scalar string to the actual scalar
sub
_read_scalar {
my
$self
=
shift
;
my
$string
=
shift
;
return
undef
if
$string
eq
'~'
;
return
$string
;
}
# Save an object to a file
sub
write
{
my
$self
=
shift
;
my
$file
=
shift
or
return
$self
->_error(
'No file name provided'
);
# Write it to the file
open
( CFG,
'>'
.
$file
) or
return
$self
->_error(
"Failed to open file '$file' for writing: $!"
);
CFG
$self
->write_string;
close
CFG;
}
# Save an object to a string
sub
write_string {
my
$self
=
shift
;
return
''
unless
@$self
;
# Iterate over the documents
my
@lines
= ();
foreach
my
$document
(
@$self
) {
# Special cases
unless
(
defined
$document
) {
push
@lines
,
'---'
;
next
;
}
unless
(
ref
$document
) {
push
@lines
,
"--- $document"
;
next
;
}
# Handle a plain list
if
(
ref
(
$document
) eq
'ARRAY'
) {
push
@lines
,
'---'
;
push
@lines
,
map
{
"- $_"
}
@$document
;
next
;
}
die
"CODE INCOMPLETE"
;
}
join
''
,
map
{
"$_\n"
}
@lines
;
}
# Set error
sub
_error {
$errstr
=
$ERROR
{
$_
[1]} ?
"$ERROR{$_[1]} ($_[1])"
:
$_
[1];
undef
;
}
# Retrieve error
sub
errstr {
$errstr
;
}
1;
__END__
=pod
=head1 NAME
YAML::Tiny - Read/Write YAML files with as little code as possible
=head1 PREAMBLE
B<WARNING: THIS MODULES IS HIGHLY EXPERIMENTAL AND SUBJECT TO CHANGE
WITHOUT NOTICE>
The YAML specification is huge. Like, B<really> huge. It contains all the
functionality of XML, except with flexibility and choice, which makes the
full specification more complex than XML.
The pure-Perl implementation L<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 B<YAML::Tiny> module, to implement
a incomplete but usable subset of the functionality, in as little code as
possible.
Now, given the YAML features one would need in order to have something
that is usable for things like META.yml and simple configuration files,
there's still enough complexity that I'm not sure if it is even possible
to do a YAML::Tiny module.
So I'm going to impose some ground rules.
Like the other C<::Tiny> modules, YAML::Tiny will have no non-core
dependencies, and work back to at least perl 5.005_03, hopefully 5.004.
I'm setting a hard-limit of 400k of memory (1/10th of YAML.pm).
I plan to implement features from the most common to the least common, but
if we hit 400k limit then we stop until we can find a way to squish the
same functionality into less code and free some up.
At this point, other than unquoted scalars, arrays, hashes and ASCII,
I promise nothing.
At present I've (literally) cut-and-pasted a L<Config::Tiny>-like set of
methods, and I've implemented enough code to handle the following.
# A comment
---
- foo
- bar
And that's it. So do B<not> use this module for anything other than
experimentation. It's only just getting started.
=head1 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' );
=head1 DESCRIPTION
C<Config::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 C<::Tiny> family of modules is specifically
intended to provide an ultralight alternative to the standard modules.
This module is primarily for reading human written files (like config files)
and generating simple human-readable report. Note that I said
B<human-readable> and not B<geek-readable>. The sort of files that your
average manager or secretary should be able to look at and make sense of.
L<YAML::Tiny> does not generate comments, it won't necesarily preserve the
order of your hashs, and it may normalise if reading in and writing out
again.
It only supports a very basic subset of the full YAML specification.
It is also 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
the module author.
If you need something with more power move up to L<YAML> (4 megabytes of\
memory overhead) or L<YAML::Syck> (requires libsyck).
To restate, L<YAML::Tiny> does B<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.
=head1 METHODS
=head2 new
The constructor C<new> creates and returns an empty C<Config::Tiny> object.
=head2 read $filename
The C<read> constructor reads a YAML file, and returns a new
C<YAML::Tiny> object containing the contents of the file.
Returns the object on success, or C<undef> on error.
When C<read> fails, C<YAML::Tiny> sets an error message internally
you can recover via C<<YAML::Tiny->errstr>>. Although in B<some>
cases a failed C<read> will also set the operating system error
variable C<$!>, not all errors do and you should not rely on using
the C<$!> variable.
=head2 read_string $string;
The C<read_string> method takes as argument the contents of a YAML file
(a YAML document) as a string and returns the C<YAML::Tiny> object for
it.
=head2 write $filename
The C<write> method generates the file content for the properties, and
writes it to disk to the filename specified.
Returns true on success or C<undef> on error.
=head2 write_string
Generates the file content for the object and returns it as a string.
=head2 errstr
When an error occurs, you can retrieve the error message either from the
C<$YAML::Tiny::errstr> variable, or using the C<errstr()> method.
=head1 SUPPORT
Bugs should be reported via the CPAN bug tracker at
For other issues, or commercial enhancement or support, contact the author.
=head1 AUTHOR
Adam Kennedy E<lt>cpan@ali.asE<gt>
=head1 SEE ALSO
L<http://ali.as/>, L<YAML>, L<YAML::Syck>, L<Config::Tiny>, L<CSS::Tiny>
=head1 COPYRIGHT
Copyright 2006 Adam Kennedy. All rights reserved.
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.
=cut