NAME

Text::FrontMatter::YAML - read the "YAML front matter" format

SYNOPSIS

    use File::Slurp;
    use Text::FrontMatter::YAML;

    # READING
    my $text_with_frontmatter = read_file("filename.md");
    my $tfm = Text::FrontMatter::YAML->new(
        document_string => $text_with_frontmatter
    );

    my $hashref  = $tfm->frontmatter_hashref;
    my $mumble   = $hashref->{'mumble'};
    my $data     = $tfm->data_text;

    # or also

    my $fh = $tfm->data_fh();
    while (defined(my $line = <$fh>)) {
        # do something with the file data
    }

    # WRITING
    my $tfm = Text::FrontMatter::YAML->new(
        frontmatter_hashref => {
            title => 'The first sentence of the "Gettysburg Address"',
            author => 'Abraham Lincoln',
            date => 18631119
        },
        data_text => "Four score and seven years ago...",
    );

    write_file("gettysburg.md", $tfm->document_string);

DESCRIPTION

Text::FrontMatter::YAML reads and writes files with so-called "YAML front matter", such as are found on GitHub (and used in Jekyll, and various other programs). It's a way of associating metadata with a file by marking off the metadata into a YAML section at the top of the file. (See "The Structure of files with front matter" for more.)

You can create an object from a string containing a full document (say, the contents of a file), or from a hashref (to turn into the YAML front matter) and a string (for the rest of the file data). The object can't be altered once it's created.

The Structure of files with front matter

Files with a block at the beginning like the following are considered to have "front matter":

    ---
    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 (---\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 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 frontmatter_hashref and data_text works in reverse, except that there's no way to specify an empty (as opposed to non-existent) YAML front matter section.

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 Encode.

METHODS

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

new

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

frontmatter_hashref

frontmatter_hashref() loads the YAML in the front matter using YAML::Tiny and returns a reference to the resulting hash.

If there is no front matter block, it returns undef.

frontmatter_text

frontmatter_text() returns the text found the front matter block, if any. The trailing triple-dash line (---), if any, is removed.

If there is no front matter block, it returns undef.

data_fh

data_fh() returns a filehandle whose contents are the data section of the file. The filehandle will be ready for reading from the beginning. A new filehandle will be returned each time data_fh() is called.

If there is no data section, it returns undef.

data_text

data_text() returns a string contaning the data section of the file.

If there is no data section, it returns undef.

document_string

document_string() returns the complete, joined front matter and data sections, suitable for writing to a file.

DIAGNOSTICS

must pass 'document_string', 'data_text', or 'frontmatter_hashref'

When calling new(), you have to pass in something to initialize the object. You can't create the object and then set the contents.

cannot pass 'document_string' with either 'frontmatter_hashref' or 'data_text'

When calling new(), you can't both pass in a complete document string and the individual hashref and data sections. Do one or the other.

you can't call <method> as a setter

Once you create the object, you can't change it.

internal error: ...

Something went wrong that wasn't supposed to, and points to a bug. Please report it to me at bug-text-frontmatter-yaml@rt.cpan.org. Thanks!

BUGS & CAVEATS

• If you create an object from a string with document_string, and then pull the string back out with document_string(), don't rely on hash keys in the YAML to be ordered the same way.

• Errors in the YAML will only be detected upon calling frontmatter_hashref(), because that's the only time that YAML::Tiny is called to parse the YAML.

Please report bugs to me at bug-text-frontmatter-yaml@rt.cpan.org or use the web interface at:

https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-FrontMatter-YAML.

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO

Jekyll - https://github.com/mojombo/jekyll/wiki/yaml-front-matter

YAML

YAML::Tiny

AUTHOR

Aaron Hall, vitahall@cpan.org

LICENSE AND COPYRIGHT

Copyright 2013-2022 Aaron Hall.

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

See http://dev.perl.org/licenses/ for more information.

cpanm Text::FrontMatter::YAML

perl -MCPAN -e shell
install Text::FrontMatter::YAML