Text::FrontMatter::YAML - read the "YAML front matter" format
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);
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.
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:
---\n
--- ---
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.
frontmatter_hashref
data_text
Except for new(), none of these methods take parameters.
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.
document_string
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() returns the text found the front matter block, if any. The trailing triple-dash line (---), if any, is removed.
---
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() returns a string contaning the data section of the file.
document_string() returns the complete, joined front matter and data sections, suitable for writing to a file.
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 ahall@vitaphone.net. Please include Text::FrontMatter::YAML in the subject line of the e-mail. Thanks!
ahall@vitaphone.net
Text::FrontMatter::YAML
When calling new(), you can't both pass in a complete document string and the individual hashref and data sections.
Once you create the object, you can't change it.
Something went wrong that wasn't supposed to, and points to a bug. Please report it to me at ahall@vitahall.org. Thanks!
ahall@vitahall.org
YAML::Tiny (available from CPAN) is used to process the YAML front matter when frontmatter_hashref() is called.
You can find documentation for this module with the perldoc command.
perldoc Text::FrontMatter::YAML
Send questions, feature requests, and bug reports to me at ahall@vitaphone.net. Please include Text::FrontMatter::YAML in the subject line of the e-mail. Thanks!
Jekyll - https://github.com/mojombo/jekyll/wiki/yaml-front-matter
YAML
YAML::Tiny
Aaron Hall, ahall@vitaphone.net
Copyright 2013 Aaron Hall.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0.
See http://dev.perl.org/licenses/ for more information.
To install Text::FrontMatter::YAML, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::FrontMatter::YAML
CPAN shell
perl -MCPAN -e shell install Text::FrontMatter::YAML
For more information on module installation, please visit the detailed CPAN module installation guide.