Pandoc::Filter - process Pandoc abstract syntax tree
The following filter flatten.pl, adopted from pandoc scripting documentation, converts level 2+ headers to regular paragraphs.
flatten.pl
use Pandoc::Filter; use Pandoc::Elements; pandoc_filter Header => sub { return unless $_->level >= 2; # keep return Para [ Emph $_->content ]; # replace };
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.
This module is a port of pandocfilters from Python to modern Perl. It provides methods and functions to aid writing Perl scripts that process a Pandoc abstract syntax tree (AST) serialized as JSON. See Pandoc::Elements for documentation of AST elements.
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:
format
transform $ast, ...; # as function $ast->transform( ... ); # or as method
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.
undef
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 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).
Return a code reference to call all actions.
Return the number of actions in this filter.
The following functions are exported by default.
Read a single line of JSON from STDIN and walk down the AST. Implicitly sets binmode UTF-8 for STDOUT.
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(<>); my $format = $ARGV[0]; Pandoc::Filter->new(@actions)->apply($ast, $format); say $ast->to_json;
Script pandocwalk, installed with this module, facilitates execution of pandoc_walk to traverse a document from command line.
pandoc_walk
Copyright 2014- Jakob Voß
GNU General Public License, Version 2
This module is heavily based on Pandoc by John MacFarlane.
To install Pandoc::Elements, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pandoc::Elements
CPAN shell
perl -MCPAN -e shell install Pandoc::Elements
For more information on module installation, please visit the detailed CPAN module installation guide.