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 has no non-core
dependencies, does not require a compiler to install, is back-compatible to
Perl 5.004, and can be inlined into other modules if needed.
In exchange for this adding this extreme flexibility, it provides support for
only a limited subset of YAML. But the subset supported contains most of the
features for the more common usese of YAML.
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
# 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 necessarily preserve the order
of your hashes, and it will normalize if reading in and writing out again.
It only supports a very basic subset of the full YAML specification.
Usage is targeted 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.
YAML TINY SPECIFICATION¶
This section of the documentation provides a specification for "YAML
Tiny", a subset of the YAML specification.
It is based on and described comparatively to the YAML 1.1 Working Draft
2004-12-28 specification, located at
<
http://yaml.org/spec/current.html>.
Terminology and chapter numbers are based on that specification.
1. Introduction and Goals¶
The purpose of the YAML Tiny specification is to describe a useful subset of the
YAML specification that can be used for typical document-oriented use cases
such as configuration files and simple data structure dumps.
Many specification elements that add flexibility or extensibility are
intentionally removed, as is support for complex datastructures, class and
object-orientation.
In general, the YAML Tiny language targets only those data structures available
in JSON, with the additional limitation that only simple keys are supported.
As a result, all possible YAML Tiny documents should be able to be transformed
into an equivalent JSON document, although the reverse is not necesarily true
(but will be true in simple cases).
As a result of these simplifications the YAML Tiny specification should be
implementable in a (relatively) small amount of code in any language that
supports Perl Compatible Regular Expressions (PCRE).
2. Introduction¶
YAML Tiny supports three data structures. These are scalars (in a variety of
forms), block-form sequences and block-form mappings. Flow-style sequences and
mappings are not supported, with some minor exceptions detailed later.
The use of three dashes "---" to indicate the start of a new document
is supported, and multiple documents per file/stream is allowed.
Both line and inline comments are supported.
Scalars are supported via the plain style, single quote and double quote, as
well as literal-style and folded-style multi-line scalars.
The use of explicit tags is not supported.
The use of "null" type scalars is supported via the ~ character.
The use of "bool" type scalars is not supported.
However, serializer implementations should take care to explicitly escape
strings that match a "bool" keyword in the following set to prevent
other implementations that do support "bool" accidentally reading a
string as a boolean
y|Y|yes|Yes|YES|n|N|no|No|NO
|true|True|TRUE|false|False|FALSE
|on|On|ON|off|Off|OFF
The use of anchors and aliases is not supported.
The use of directives is supported only for the %YAML directive.
Processes
The YAML specification dictates three-phase serialization and three-phase
deserialization.
The YAML Tiny specification does not mandate any particular methodology or
mechanism for parsing.
Any compliant parser is only required to parse a single document at a time. The
ability to support streaming documents is optional and most likely
non-typical.
Because anchors and aliases are not supported, the resulting representation
graph is thus directed but (unlike the main YAML specification)
acyclic.
Circular references/pointers are not possible, and any YAML Tiny serializer
detecting a circular reference should error with an appropriate message.
Presentation Stream
YAML Tiny is notionally unicode, but support for unicode is required if the
underlying language or system being used to implement a parser does not
support Unicode. If unicode is encountered in this case an error should be
returned.
Loading Failure Points
YAML Tiny parsers and emitters are not expected to recover from adapt to errors.
The specific error modality of any implementation is not dictated (return
codes, exceptions, etc) but is expected to be consistent.
4. Syntax¶
Character Set
YAML Tiny streams are implemented primarily using the ASCII character set,
although the use of Unicode inside strings is allowed if support by the
implementation.
Specific YAML Tiny encoded document types aiming for maximum compatibility
should restrict themselves to ASCII.
The escaping and unescaping of the 8-bit YAML escapes is required.
The escaping and unescaping of 16-bit and 32-bit YAML escapes is not required.
Indicator Characters
Support for the "~" null/undefined indicator is required.
Implementations may represent this as appropriate for the underlying language.
Support for the "-" block sequence indicator is required.
Support for the "?" mapping key indicator is
not required.
Support for the ":" mapping value indicator is required.
Support for the "," flow collection indicator is
not required.
Support for the "[" flow sequence indicator is
not required,
with one exception (detailed below).
Support for the "]" flow sequence indicator is
not required,
with one exception (detailed below).
Support for the "{" flow mapping indicator is
not required,
with one exception (detailed below).
Support for the "}" flow mapping indicator is
not required,
with one exception (detailed below).
Support for the "#" comment indicator is required.
Support for the "&" anchor indicator is
not required.
Support for the "*" alias indicator is
not required.
Support for the "!" tag indicator is
not required.
Support for the "|" literal block indicator is required.
Support for the ">" folded block indicator is required.
Support for the "'" single quote indicator is required.
Support for the """ double quote indicator is required.
Support for the "%" directive indicator is required, but only for the
special case of a %YAML version directive before the "---" document
header, or on the same line as the document header.
For example:
%YAML 1.1
---
- A sequence with a single element
Special Exception:
To provide the ability to support empty sequences and mappings, support for the
constructs [] (empty sequence) and {} (empty mapping) are required.
For example,
%YAML 1.1
# A document consisting of only an empty mapping
--- {}
# A document consisting of only an empty sequence
--- []
# A document consisting of an empty mapping within a sequence
- foo
- {}
- bar
Syntax Primitives
Other than the empty sequence and mapping cases described above, YAML Tiny
supports only the indentation-based block-style group of contexts.
All five scalar contexts are supported.
Indentation spaces work as per the YAML specification in all cases.
Comments work as per the YAML specification in all simple cases. Support for
indented multi-line comments is
not required.
Separation spaces work as per the YAML specification in all cases.
YAML Tiny Character Stream
The only directive supported by the YAML Tiny specification is the %YAML
language/version identifier. Although detected, this directive will have no
control over the parsing itself.
The parser must recognise both the YAML 1.0 and YAML 1.1+ formatting of this
directive (as well as the commented form, although no explicit code should be
needed to deal with this case, being a comment anyway)
That is, all of the following should be supported.
--- #YAML:1.0
- foo
%YAML:1.0
---
- foo
% YAML 1.1
---
- foo
Support for the %TAG directive is
not required.
Support for additional directives is
not required.
Support for the document boundary marker "---" is required.
Support for the document boundary market "..." is
not required.
If necessary, a document boundary should simply by indicated with a
"---" marker, with not preceding "..." marker.
Support for empty streams (containing no documents) is required.
Support for implicit document starts is required.
That is, the following must be equivalent.
# Full form
%YAML 1.1
---
foo: bar
# Implicit form
foo: bar
Nodes
Support for nodes optional anchor and tag properties are
not required.
Support for node anchors is
not required.
Support for node tags is
not required.
Support for alias nodes is
not required.
Support for flow nodes is
not required.
Support for block nodes is required.
Scalar Styles
Support for all five scalar styles are required as per the YAML specification,
although support for quoted scalars spanning more than one line is
not
required.
Support for the chomping indicators on multi-line scalar styles is required.
Collection Styles
Support for block-style sequences is required.
Support for flow-style sequences is
not required.
Support for block-style mappings is required.
Support for flow-style mappings is
not required.
Both sequences and mappings should be able to be arbitrarily nested.
Support for plain-style mapping keys is required.
Support for quoted keys in mappings is
not required.
Support for "?"-indicated explicit keys is
not required.
Here endeth the specification.
Additional Perl-Specific Notes¶
For some Perl applications, it's important to know if you really have a number
and not a string.
That is, in some contexts is important that 3 the number is distinctive from
"3" the string.
Because even Perl itself is not trivially able to understand the difference
(certainly without XS-based modules) Perl implementations of the YAML Tiny
specification are not required to retain the distinctiveness of 3 vs
"3".
METHODS¶
new¶
The constructor "new" creates and returns an empty
"YAML::Tiny" object.
read $filename¶
The "read" constructor reads a YAML file from a file name, and returns
a new "YAML::Tiny" object containing the parsed content.
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" constructor reads a YAML file from a file name, and returns
a new "YAML::Tiny" object containing the parsed content.
Returns the object on success, or "undef" on error.
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
<
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 - 2012 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.