view release on metacpan or  search on metacpan

lib/Text/FrontMatter/YAML.pm  view on Meta::CPAN

    author: Aaron Hall
    email:  ahall@vitahall.org
    module: Text::FrontMatter::YAML
    version: 0.50
    ---
    This is the rest of the file data, and isn't part of
    the front matter block. This section of the file is not
    interpreted in any way by Text::FrontMatter::YAML.

It is not an error to open or create documents that have no front matter
block, nor those that have no data block.

Triple-dashed lines (C<---\n>) mark the beginning of the two sections.
The first triple-dashed line marks the beginning of the front matter. The
second such line marks the beginning of the data section. Thus the
following is a valid document:

    ---
    ---

That defines a document with defined but empty front matter and data
sections. The triple-dashed lines are stripped when the front matter or
data are returned as text.

If the input has front matter, a triple-dashed line must be the first line
of the file. If not, the file is considered to have no front matter; it's
all data. frontmatter_text() and frontmatter_hashref() will return
undef in this case.

In input with a front matter block, the first line following the next
triple-dashed line begins the data section. If there I<is> no second
triple-dashed line the file is considered to have no data section, and
data_text() and data_fh() will return undef.

Creating an object with C<frontmatter_hashref> and C<data_text> works
in reverse, except that there's no way to specify an empty (as opposed
to non-existent) YAML front matter section.

=head2 Encoding

Text::FrontMatter::YAML operates on Perl character strings. Decode your
data from its original encoding before passing it in; re-encode it
after getting it back. See L<Encode>.

=head1 METHODS

Except for new(), none of these methods take parameters.

=head2 new

new() creates a new Text::FrontMatter::YAML object. You can pass either
C<document_string> with the full text of a document (see L<The Structure
of files with front matter>) or one or both of C<frontmatter_hashref>
and C<data_text>.

=cut

sub new {
    my $class = shift;
    my $self  = {};
    bless $self => $class;

    my %args = @_;

    # make sure we get something to init with
    unless (
        exists $args{'document_string'}
        || exists $args{'frontmatter_hashref'}
        || exists $args{'data_text'}
    )
    {
        croak "must pass 'document_string', 'data_text', or 'frontmatter_hashref'";
    }

    # disallow passing incompatible arguments
    unless (
        (exists $args{'document_string'})
          xor
        (exists $args{'frontmatter_hashref'} || exists $args{'data_text'})
    )
    {
        croak "cannot pass 'document_string' with either "
            . "'frontmatter_hashref' or 'data_text'";
    }

    # initialize from whatever we've got
    if (exists $args{'document_string'}) {
        $self->_init_from_string($args{'document_string'});
    }
    elsif (exists $args{'frontmatter_hashref'} or exists $args{'data_text'}) {
        $self->_init_from_sections($args{'frontmatter_hashref'}, $args{'data_text'});
    }
    else {
        die "internal error: didn't get any valid init arg"
    }

    return $self;
}



sub _init_from_sections {
    my $self    = shift;
    my $hashref = shift;
    my $data    = shift;

    $self->{'yaml'} = YAML::Tiny::Dump($hashref);
    $self->{'data'} = $data;

    if (defined $hashref) {
        # YAML::Tiny prefixes the '---' so we don't need to
        $self->{'document'} = $self->{'yaml'};
        $self->{'document'} .= "---\n" if defined($data);
    }

    if (defined $data) {
        $self->{'document'} .= $data;
    }
}