hkod/frontmatter

A context aware frontmatter parser that supports multiple formats and uses a clean OOP architecture

frontmatter

, _(*1)

A context aware frontmatter parser that supports multiple formats and uses a clean OOP architecture., _(*2)

Front matter is metadata located at the top of a file wrapped in delimiting line tokens, usually ---. The front matter may be formatted using YAML, Json or any ohter simliar format such as NEON or TOML., _(*3)

Supported formats:, _(*4)

• Json
• INI
• YAML (require symfony/yaml)
• Markdown (require erusev/parsedown)
• Mustache (require mustache/mustache)

Parsers are simple callables, super easy to add more formats., _(*5)

Installation

composer require hkod/frontmatter

Usage

A standard parser with yaml frontmatter and markdown body:, _(*6)

, _(*7)

$parser = new \hkod\frontmatter\Parser(
    new \hkod\frontmatter\YamlParser,
    new \hkod\frontmatter\MarkdownParser
);

$result = $parser->parse("---
key: value
---
This is a **template**
");

// value
echo $result->getFrontmatter()['key'];

// 

This is a template, (*8)


echo $result->getBody();

Specify the front matter delimiter

Note that the delimiting tokens always represents full lines., _(*9)

You may set the delimiters when creating the block parser., _(*10)

$parser = new \hkod\frontmatter\Parser(
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\BlockParser('***', '***')
);

$result = $parser->parse("***
frontmatter
***
body
");

// frontmatter
echo $result->getFrontmatter();

Putting the frontmatter last

Note that since the delimiting tokens represent a line the last line must end whit a new line (or similar) or it won't be recognized by the parser., _(*11)

Frontmatter also supports an inverted block parser, where the frontmatter is expected to bee last instead of first., _(*12)

$parser = new \hkod\frontmatter\Parser(
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\InvertedBlockParser
);

$result = $parser->parse("
This is a the body
---
This is the frontmatter
---
");

// "This is the frontmatter"
echo $result->getFrontmatter();

Passing a context

When parsing you may pass a context to the parser and it will in turn be passed along to all subsequent parsers. Context dependet parsers may for example expand templates..., _(*13)

$parser = new \hkod\frontmatter\Parser(
    new \hkod\frontmatter\VoidParser,
    new \hkod\frontmatter\MustacheParser
);

$context = ['variable' => 'foobar'];

$result = $parser->parse("{{variable}}", $context);

// foobar
echo $result->getBody();

Creating complex parsers

, _(*14)

$parser = (new \hkod\frontmatter\ParserBuilder)
    ->addFrontmatterPass(new \hkod\frontmatter\MustacheParser)
    ->addFrontmatterPass(new \hkod\frontmatter\YamlParser)
    ->addBodyPass(new \hkod\frontmatter\MustacheParser)
    ->addBodyPass(new \hkod\frontmatter\MarkdownParser)
    ->setBlockParser(new \hkod\frontmatter\BlockParser('***', '***'))
    ->buildParser();

$document = "***
key: {{variable}}
***
This is a **{{text}}** template
";

$context = ['variable' => 'value', 'text' => 'markdown'];

$result = $parser->parse($document, $context);

// value
echo $result->getFrontmatter()['key'];

// 

This is a markdown template, (*15)



echo $result->getBody();