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