NAME

       Pandoc::Metadata - pandoc document metadata

DESCRIPTION

       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.