This template makes extensive use of the Data::Rmap module to iterate recursively through the Pandoc document data, so you should read the documentation of that module.

It also, of course, uses the JSON module, so you may want to familiarize yourself with that.

You should also familiarize yourself with pandoc's JSON output, not least to learn what kind of data pandoc expects a filter to return!

As a Perl hacker you may be best helped by seeing what the Perl data structures look like which the JSON module makes out of the JSON it receives from pandoc. That's very easy if you use JSON::XS and have the Data::Dump module installed:

$ pandoc -w json | json_xs -t dump
*   Some *emphatic* Markdown with `code`{#id .class attr=val}.
[
  { unMeta => {} },
  [
    {
      c => [
             [
               {
                 c => [
                        { c => "Some", t => "Str" },
                        { c => [], t => "Space" },
                        { c => [{ c => "emphatic", t => "Str" }], t => "Emph" },
                        { c => [], t => "Space" },
                        { c => "Markdown", t => "Str" },
                        { c => [], t => "Space" },
                        { c => "with", t => "Str" },
                        { c => [], t => "Space" },
                        { c => [["id", ["class"], [["attr", "val"]]], "code"], t => "Code" },
                        { c => ".", t => "Str" },
                      ],
                 t => "Plain",
               },
             ],
           ],
      t => "BulletList",
    },
  ],
]

Do this with the kind of Markdown snippets you want to modify, and with the Markdown equivalents of the kind of structures you want to return, study them carefully, and you will soon get an idea of what the data looks like.

my $opts_href = get_meta_opts( 
    +{ doc => $doc, opts => \@opts, default => \%opts, prefix => $pfx }
);

doc => $doc

Data structure representing a Pandoc AST decoded from JSON produced by pandoc. Required.

opts => \@opts

Arrayref of option names, without prefix. Required.

default => \%opts

Optional hashref of option defaults, keyed on option names without prefix. If an option is missing from the metadata it will get the corresponding value from this hashref.

prefix => $pfx

optional string prefixed to option names to get metadata keys if the option name is 'foo' and the prefix is 'filter-name-' then the metadata key for that option is 'filter-name-foo', but the key in the returned $opts_href will be 'foo'. This is so that you can tell which options are for this particular filter, but won't need to type the prefix when accessing elements in the options hashref.

Returns a hashref with OPTION => VALUE pairs, without prefix.

Rules for finding an option value:

1. If the metadata element is not a MetaMap or MetaList:

   Returns the value of the first Str, MetaString, MetaBool, Code or CodeBlock element found in the metadata value.

2. If the metadata element is a MetaMap:

   Returns a hashref where the keys are the keys of the MetaMap and the values are obtained by recursively applying these rules to the corresponding MetaMap value.

3. If the metadata element is a MetaList:

   Returns a plain arrayref with the values obtained from the MetaList values by recursively applying these rules.

Bottom line: you get a data structure as similar to your metadata YAML block, with non-list, non-map values truncated as per rule 1. This means you will get strings or JSON::Boolean objects (which stringify as 0|1), possibly as values of possibly nested hash or array references.

rmap_hash { BLOCK } $doc;

The BLOCK is actually a subroutine closure. It will be called once for each hashref in $doc, with $_ aliased to the hashref.

If you want to abort processing of the current element you should return without an argument; this is the equivalent of next in a true loop block.

If you want to replace the current element with another you should assign the new element to $_. The return value from BLOCK isn't very useful in our case, since Data::

Normally you should first check that $_

Normally the hashref represents a JSON object which represents an element in the pandoc AST; however this is not always true in the metadata section, so you should at least check that there is a non-false 't' key and a defined 'c' key in the hashref. If someone populates a metadata map with two such keys disaster may ensue, so you might want to warn against that! The return value of the BLOCK is ignored by most filters, but Data::Rmap collects whatever is returned from the BLOCK and returns the collected list from rmap_hash()! Return an empty list/return without arguments to break out of BLOCK. To not visit the contents of the current hashref break out of the BLOCK by calling cut(); To alter or replace the current element alter the contents of $_ or assign to $_, Just make sure that $_ contains a valid element object hashref!

Make sure to read the documentation for the Data::Rmap module.

rmap_element_lists { BLOCK } $doc;

The BLOCK is actually a subroutine closure. It will be called once for each element in each list in $doc with only hashrefs as values, with $_ aliased to the hashref. Normally the hashref represents a JSON object which represents an element in the pandoc AST; however this is not always true in the metadata section, so you should at least check that there is a non-false 't' key and a defined 'c' key in the hashref. If someone populates a metadata map with two such keys disaster may ensue, so you might want to warn against that! Whatever is returned from the BLOCK is pushed onto the replacement list: to keep the original hashref return $_ to skip this element return an empty list/return without elements Only ever return an empty list or a (list of) valid element object hash(es)!