NAME

       Pandoc::Filter - process Pandoc abstract syntax tree

SYNOPSIS

       Filter "flatten.pl", adopted from pandoc scripting documentation
       <http://pandoc.org/scripting.html>, converts level 2+ headers to regular paragraphs:

           use Pandoc::Filter;
           use Pandoc::Elements;

           pandoc_filter Header => sub {
               return unless $_->level >= 2;       # keep
               return Para [ Emph $_->content ];   # replace
           };

       Apply this filter on a Markdown file like this:

           pandoc --filter flatten.pl -t markdown < input.md

       See <https://metacpan.org/pod/distribution/Pandoc-Elements/examples/> for more examples of
       filters.

DESCRIPTION

       Pandoc::Filter provides tools to modify the abstract syntax tree (AST) of Pandoc
       <http://pandoc.org/> documents. See Pandoc::Elements for AST elements that can be modified
       by filters.

       The function interface (see "FUNCTIONS") directly reads AST and format from STDIN and ARGV
       and prints the transformed AST to STDOUT.

       The object oriented interface (see "METHODS") requires to:

           my $filter = Pandoc::Filter->new( ... );  # create a filter object
           $filter->apply( $ast, $format );          # pass it an AST for processing

       If you don't need the "format" parameter, consider using the interface provided by module
       Pandoc::Walker instead. It can be used both:

           transform $ast, ...;        # as function
           $ast->transform( ... );     # or as method

ACTIONS

       An action is a code reference that is executed on matching document elements of an AST.
       The action is passed a reference to the current element, the output format (the empty
       string by default), and the document metadata (an empty hash by default).  The current
       element is also given in the special variable $_ for convenience.

       The action is expected to return an element, an empty array reference, or "undef" to
       modify, remove, or keep a traversed element in the AST.

METHODS

   new( @actions | %actions )
       Create a new filter object with one or more actions (see "ACTIONS"). If actions are given
       as hash, key values are used to check which elements to apply for, e.g.

           Pandoc::Filter->new(
               Header                 => sub { ... },
               'Suscript|Superscript' => sub { ... }
           )

   apply( $ast [, $format [, $metadata ] ] )
       Apply all actions to a given abstract syntax tree (AST). The AST is modified in place and
       also returned for convenience. Additional argument format and metadata are also passed to
       the action function. Metadata is taken from the Document by default (if the AST is a
       Document root).

   action
       Return a code reference to call all actions.

FUNCTIONS

       The following functions are exported by default.

   pandoc_filter( @actions | %actions )
       Read a single line of JSON from STDIN, apply actions on the document content and print the
       resulting AST as single line of JSON. Filter documentation is printed if filter called
       with command line argument "--help", "-h", or "-?".  See Pod::Pandoc for extended ways to
       process filter documentation.

FILTER MODULES

       Pandoc::Filter::HeaderIdentifiers
       Pandoc::Filter::Multifilter
       Pandoc::Filter::ImagesFromCode

SEE ALSO

       This module is a port of pandocfilters <https://github.com/jgm/pandocfilters> from Python
       to modern Perl.

COPYRIGHT AND LICENSE

       Copyright 2014- Jakob Voss

       GNU General Public License, Version 2

       This module is heavily based on Pandoc by John MacFarlane.