NAME

       Pandoc::Filter - process Pandoc abstract syntax tree

SYNOPSIS

       The following 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;
               return Para [ Emph $_->content ];
           };

       To apply this filter on a Markdown file:

           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 is a port of pandocfilters <https://github.com/jgm/pandocfilters> from
       Python to modern Perl.  The module provide provides functions to aid writing Perl scripts
       that process a Pandoc <http://pandoc.org/> abstract syntax tree (AST) serialized as JSON.
       See Pandoc::Elements for documentation of AST elements.

       This module is based on Pandoc::Walker and its function "transform". Please consider using
       its function interface ("transform", "query", "walk") instead of this module.

METHODS

   new( @actions | %actions )
       Create a new filter with one or more action functions, given as code reference(s). Each
       function is expected to return an element, an empty array reference, or "undef" to modify,
       remove, or keep a traversed element in the AST. The current element is passed to an action
       function both as first argument and in the special variable $_. Output format (if
       specified) and document metadata are passed as second and third argument.

       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.

   size
       Return the number of actions in this filter.

FUNCTIONS

       The following functions are exported by default.

   pandoc_walk( @actions | %actions )
       Read a single line of JSON from STDIN and walk down the AST.  Implicitly sets binmode
       UTF-8 for STDOUT.

   pandoc_filter( @actions | %actions )
       Read a single line of JSON from STDIN, apply actions and print the resulting AST as single
       line of JSON. This function is roughly equivalent to

           my $ast = Pandoc::Elements::pandoc_json(<>);
           Pandoc::Filter->new(@actions)->apply($ast, @ARGV ? $ARGV[0] : ());
           say $ast->to_json;

   stringify( $ast )
       Walks the ast and returns concatenated string content, leaving out all formatting. This
       function is also accessible as method of Pandoc::Element since version 0.12, so it will be
       removed as exportable function in a later version.

SEE ALSO

       Script pandocwalk installed with this module facilitates execution of "pandoc_walk" to
       traverse a document.

COPYRIGHT AND LICENSE

       Copyright 2014- Jakob Voss

       GNU General Public License, Version 2

       This module is heavily based on Pandoc by John MacFarlane.