Pandoc::Metadata(3pm)

Overview

Document metadata such as author, title, and date can be embedded in different documents formats. Metadata can be provided in Pandoc markdown format with metadata blocks <http://pandoc.org/MANUAL.html#metadata-blocks> at the top of a markdown file or in YAML format like this:

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

Pandoc supports document metadata build of strings ("MetaString"), boolean values ("MetaBool"), lists ("MetaList"), key-value maps ("MetaMap"), lists of inline elements ("MetaInlines") and lists of block elements ("MetaBlocks"). Simple strings and boolean values can also be specified via pandoc command line option "-M" or "--metadata":

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

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

Common methods

All Metadata Elements support common element methods ("name", "to_json", "string", ...) and return true for method "is_meta".

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

Called without an argument this method returns an unblessed deep copy of the metadata element. Plain keys at the root level (unless they start with "/") and JSON Pointer expressions (RFC 6901 <http://tools.ietf.org/html/rfc6901>) can be used to select subfields. Note that JSON Pointer escapes slash as "~1" and character "~" as "~0". URI Fragment syntax is not supported.

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

As a debugging aid you can set option "strict" to a true value. In this case the method will "croak" if an invalid pointer, invalid array index, non-existing key or non-existing array index is encountered.

Instances of MetaInlines and MetaBlocks are stringified by unless option "element" is set to "keep".

Setting option "boolean" to "JSON::PP" will return "JSON::PP:true" or "JSON::PP::false" for MetaBool instances.

Metadata elements

MetaString

A plain text string metadata value.

    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.

    MetaList [ @values ]
    metadata [ @values ]

MetaMap

A map of keys to other metadata elements.

    MetaMap { %map }
    metadata { %map }

MetaInlines

Container for a list of inlines in metadata.

    MetaInlines [ @inlines ]

MetaBlocks

Container for a list of blocks in metadata.

    MetaBlocks [ @blocks ]

The "string" method concatenates all stringified content blocks separated by empty lines.

Releases

3 releases since Debian 10 (Buster); the text changed 2 times.

10
12
13