-
-
20 Jan 2022 03:16:27 UTC
- Distribution: Text-FrontMatter-YAML
- Module version: 1.00
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues (0)
- Testers (303 / 0 / 1)
- Kwalitee
Bus factor: 1- 93.44% Coverage
- License: perl_5
- Perl: v5.10.1
- Activity
24 month- Tools
- Download (10.13KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Carp
- Encode
- YAML::Tiny
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
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
anddata_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 offrontmatter_hashref
anddata_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.
Module Install Instructions
To install Text::FrontMatter::YAML, copy and paste the appropriate command in to your terminal.
cpanm Text::FrontMatter::YAML
perl -MCPAN -e shell install Text::FrontMatter::YAML
For more information on module installation, please visit the detailed CPAN module installation guide.