=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 NAME

Tiny::YAML - YAML::Tiny Done Right

=for html
<a href="https://travis-ci.org/ingydotnet/tiny-yaml-pm"><img src="https://travis-ci.org/ingydotnet/tiny-yaml-pm.png" alt="tiny-yaml-pm"></a>
<a href="https://coveralls.io/r/ingydotnet/tiny-yaml-pm?branch=master"><img src="https://coveralls.io/repos/ingydotnet/tiny-yaml-pm/badge.png" alt="tiny-yaml-pm"></a>

=head1 PREAMBLE

Don't even look at this yet. It's a super early release and will be
bootstrapping for a while.

This module uses a real grammar to parse/load YAML.

Stay tuned...

TODO - Funny rant about the shortcomings of YAML::Tiny

=head1 SYNOPSIS

Assuming C<file.yaml> like this:

    ---
    rootproperty: blah
    section:
      one: two
      three: four
      Foo: Bar
      empty: ~

Read and write C<file.yaml> like this:

    use Tiny::YAML;

    # Open the config
    my $data = Tiny::YAML::LoadFile( 'file.yaml' );

    # Get a reference to the first document
    my $config = $data->[0];

    # Or read properties directly
    my $root = $data->[0]->{rootproperty};
    my $one  = $data->[0]->{section}->{one};
    my $Foo  = $data->[0]->{section}->{Foo};

    # Change data directly
    $data->[0]->{newsection} = { this => 'that' }; # Add a section
    $data->[0]->{section}->{Foo} = 'Not Bar!';     # Change a value
    delete $data->[0]->{section};                  # Delete a value

    # Save the document back to the file
    Tiny::YAML::DumpFile( 'file.yaml' );

To create a new YAML file from scratch:

    # Create a new object with a single hashref document
    my $data = Dump( { wibble => "wobble" } );

    # Add an arrayref document
    push @$data, [ 'foo', 'bar', 'baz' ];

    # Save both documents to a file
    $data->( 'data.yaml' );

Then C<data.yaml> will contain:

    ---
    wibble: wobble
    ---
    - foo
    - bar
    - baz

=head1 DESCRIPTION

C<Tiny::YAML> 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 C<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 I<human-
readable> and not I<geek-readable>. The sort of files that your average
manager or secretary should be able to look at and make sense of.

L<Tiny::YAML> does not generate comments, it won't necessarily 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 targeted at files like Perl's META.yaml, 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 Tiny::YAML that someone is me.

If you need something with more power move up to L<YAML> (7 megabytes of
memory overhead) or L<YAML::XS> (6 megabytes memory overhead and requires a C
compiler).

To restate, L<Tiny::YAML> does I<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 FUNCTIONS

Tiny::YAML implements a number of functions to add compatibility with the
L<YAML> API. These should be a drop-in replacement.

=over

=item C<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 structures and dumps them into a serialized form.

It returns a character string containing the YAML stream. Be sure to encode it
as UTF-8 before serializing to a file or socket.

The structures can be references or plain scalars.

Dies on any error.

=item C<Load>

    my @data_structures = Load(string-containing-a-YAML-stream);

Turn YAML into Perl data. This is the opposite of Dump.

Just like L<Storable>'s thaw() function or the eval() function in relation to
L<Data::Dumper>.

It parses a character string containing a valid YAML stream into a list
of Perl data structures representing the individual YAML documents. Be
sure to decode the character string correctly if the string came from a
file or socket.

    my $last_data_structure = Load(string-containing-a-YAML-stream);

For consistency with YAML.pm, when Load is called in scalar context, it
returns the data structure corresponding to the last of the YAML documents
found in the input stream.

Dies on any error.

=item C<DumpFile(filepath, list)>

Writes the YAML stream to a file with UTF-8 encoding instead of just
returning a string.

Dies on any error.

=item C<LoadFile(filepath)>

Reads the YAML stream from a UTF-8 encoded file instead of a string.

Dies on any error.

=back

=head1 TINY YAML SPECIFICATION

This section of the documentation provides a specification for "Tiny YAML", 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 L<http://yaml.org/spec/current.html>.

Terminology and chapter numbers are based on that specification.

=head2 1. Introduction and Goals

The purpose of the Tiny YAML 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 data structures, class and
object-orientation.

In general, the Tiny YAML language targets only those data structures
available in JSON, with the additional limitation that only simple keys are
supported.

As a result, all possible Tiny YAML documents should be able to be transformed
into an equivalent JSON document, although the reverse is not necessarily true
(but will be true in simple cases).

As a result of these simplifications the Tiny YAML specification should be
implementable in a (relatively) small amount of code in any language that
supports Perl Compatible Regular Expressions (PCRE).

=head2 2. Introduction

Tiny YAML 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 C<---> 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 C<null> type scalars is supported via the ~ character.

The use of I<bool> type scalars is not supported.

However, serializer implementations should take care to explicitly escape
strings that match a I<bool> keyword in the following set to prevent
other implementations that do support I<bool> accidentally reading a
string as a boolean

    true|false|null

The use of anchors and aliases is not supported.

The use of directives is supported only for the %YAML directive.

=head2 3. Processing Tiny YAML Information

=over

=item Processes

The YAML specification dictates three-phase serialization and three-phase
deserialization.

The Tiny YAML 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) I<acyclic>.

Circular references/pointers are not possible, and any Tiny YAML serializer
detecting a circular reference should error with an appropriate message.

=item Presentation Stream

Tiny YAML reads and write UTF-8 encoded files. Operations on strings expect or
produce Unicode characters not UTF-8 encoded bytes.

=item Loading Failure Points

Tiny YAML parsers and emitters are not expected to recover from, or adapt to,
errors. The specific error modality of any implementation is not dictated
(return codes, exceptions, etc.) but is expected to be consistent.

=back

=head2 4. Syntax

=over

=item Character Set

Tiny YAML streams are processed in memory as Unicode characters and
read/written with UTF-8 encoding.

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.

=item Indicator Characters

Support for the C<~> null/undefined indicator is required.

Implementations may represent this as appropriate for the underlying language.

Support for the C<-> block sequence indicator is required.

Support for the C<?> mapping key indicator is I<not> required.

Support for the C<:> mapping value indicator is required.

Support for the C<,> flow collection indicator is I<not> required.

Support for the C<[> flow sequence indicator is I<not> required, with one
exception (detailed below).

Support for the C<]> flow sequence indicator is I<not> required, with one
exception (detailed below).

Support for the C<{> flow mapping indicator is I<not> required, with one
exception (detailed below).

Support for the C<}> flow mapping indicator is I<not> required, with one
exception (detailed below).

Support for the C<#> comment indicator is required.

Support for the C<&> anchor indicator is I<not> required.

Support for the C<*> alias indicator is I<not> required.

Support for the C<!> tag indicator is I<not> required.

Support for the C<|> literal block indicator is required.

Support for the C<< > >> folded block indicator is required.

Support for the C<'> single quote indicator is required.

Support for the C<"> double quote indicator is required.

Support for the C<%> directive indicator is required, but only for the special
case of a %YAML version directive before the C<---> document header, or on the
same line as the document header.

=back

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

=over

=item Syntax Primitives


=back

Other than the empty sequence and mapping cases described above, Tiny YAML
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 I<not> required.

Separation spaces work as per the YAML specification in all cases.

=over

=item Tiny YAML Character Stream


=back

The only directive supported by the Tiny YAML 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 I<not> required.

Support for additional directives is I<not> required.

Support for the document boundary marker C<---> is required.

Support for the document boundary market C<...> is I<not> required.

If necessary, a document boundary should simply by indicated with a C<--->
marker, with not preceding C<...> 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

=over

=item Nodes


=back

Support for nodes optional anchor and tag properties is I<not> required.

Support for node anchors is I<not> required.

Support for node tags is I<not> required.

Support for alias nodes is I<not> required.

Support for flow nodes is I<not> required.

Support for block nodes is required.

=over

=item Scalar Styles


=back

Support for all five scalar styles is required as per the YAML
specification, although support for quoted scalars spanning more than one
line is I<not> required.

Support for multi-line scalar documents starting on the header is not
required.

Support for the chomping indicators on multi-line scalar styles is required.

=over

=item Collection Styles


=back

Support for block-style sequences is required.

Support for flow-style sequences is I<not> required.

Support for block-style mappings is required.

Support for flow-style mappings is I<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 I<not> required.

Support for C<?>-indicated explicit keys is I<not> required.

Here endeth the specification.

=head2 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
C<3> the string.

Because even Perl itself is not trivially able to understand the difference
(certainly without XS-based modules) Perl implementations of the Tiny YAML
specification are not required to retain the distinctiveness of 3 vs C<3>.

=head1 SUPPORT

Bugs should be reported via the CPAN bug tracker at L<http://github.com/ingydotnet/tiny-yaml-
pm/issues>

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 SEE ALSO

=over

=item L<YAML::Tiny>

=item L<YAML>

=item L<YAML::Syck>

=item L<Config::Tiny>

=item L<CSS::Tiny>


=back

=head1 COPYRIGHT

Copyright 2014 Ingy döt Net

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

=cut
