Pandoc::Metadata(3pm)

✨ Pandoc::Metadata ✨

okay bestie, so this is the Pandoc::Metadata page from the User Contributed Perl Documentation — yep, perl, she's vintage but she SERVES 💅 stay with me.

🌸 NAME 🌸

Pandoc::Metadata — pandoc document metadata. that's it, that's the name, short and iconic.

---

🦋 DESCRIPTION 🦋

so like, document metadata?? author, title, date, all that?? it can be embedded in different document formats, which is lowkey kind of a lot when you think about it.

you can hand over your metadata in Pandoc markdown format using metadata blocks (http://pandoc.org/MANUAL.html#metadata-blocks) at the top of a markdown file — or in YAML format, like literally this:

---
title: a title
author:
  - first author
  - second author
published: true
...

and Pandoc supports document metadata built out of all of these:

• strings (MetaString)
• boolean values (MetaBool)
• lists (MetaList)
• key-value maps (MetaMap)
• lists of inline elements (MetaInlines)
• lists of block elements (MetaBlocks)

simple strings and boolean values can also be specified straight through the pandoc command line option -M or --metadata, like:

pandoc -M key=string
pandoc -M key=false
pandoc -M key=true
pandoc -M key

and then the Perl module Pandoc::Elements exports functions to construct metadata elements in the internal document model — plus the general helper function metadata. 🫶

---

👑 COMMON METHODS 👑

every single Metadata Element supports the common element methods — name, to_json, string, ... — and returns true for the method is_meta. no cap. ✨

🌈 value( [ $key | $pointer ] [ %options ] ) 🌈

call it with no argument and it hands you back an unblessed deep copy of the metadata element. cute, fresh, yours to keep. 💖

now, for peeking into subfields you've got options:

• plain keys at the root level — but ONLY if they don't start with /
• JSON Pointer expressions (RFC 6901, http://tools.ietf.org/html/rfc6901)

okay important: JSON Pointer escapes slash as ~1 and the character ~ as ~0. and URI Fragment syntax is NOT supported. just so you know. 😭

look how pretty this is:

$doc->value;                   # full metadata
$doc->value("");               # full metadata, explicitly
$doc->value('/author');        # author field
$doc->value('author');         # author field, plain key
$doc->value('/author/name');   # name subfield of author field
$doc->value('/author/0');      # first author field
$doc->value('/author/0/name'); # name subfield of first author field
$doc->value('/~1~0');          # metadata field '/~'
$doc->value('/');              # field with empty string as key

returns undef if the selected field does not exist. rip. 💀

as a debugging aid you can set the option strict to a true value. in that case the method will croak if it runs into:

• an invalid pointer
• an invalid array index
• a non-existing key
• a non-existing array index

instances of MetaInlines and MetaBlocks get stringified — unless option element is set to keep.

and setting option boolean to JSON::PP will return JSON::PP:true or JSON::PP::false for MetaBool instances. star behavior honestly ⭐

---

🎀 METADATA ELEMENTS 🎀

🍓 MetaString 🍓

a plain text string metadata value. simple. gorgeous. no notes.

MetaString $string
metadata "$string"

🍓 MetaBool 🍓

a Boolean metadata value. the special values false and FALSE are recognized as false in addition to normal false values (0, undef, "", ...).

MetaBool $value
metadata JSON::true()
metadata JSON::false()

🍓 MetaList 🍓

a list of other metadata elements. nesting rights!! 🌸

MetaList [ @values ]
metadata [ @values ]

🍓 MetaMap 🍓

a map of keys to other metadata elements. keys, meet values, values, meet keys 💜

MetaMap { %map }
metadata { %map }

🍓 MetaInlines 🍓

a container for a list of inlines in metadata.

MetaInlines [ @inlines ]

🍓 MetaBlocks 🍓

a container for a list of blocks in metadata.

MetaBlocks [ @blocks ]

and hiii, one more thing — the string method concatenates all stringified content blocks separated by empty lines. 🧚

---

and that's the whole page bestie, you ate it, you understood it, go forth and metadata responsibly 💅✨

this was written by the 😭 User Contributed Perl Documentation crew, running on perl v5.38.2, dated 2024-08-03 — mwah, bye 🫶