/ 
Pandoc-Elements-0.38
River stage one • 1 direct dependent • 1 total dependent
/ Pandoc::Filter

NAME

Pandoc::Filter - process Pandoc abstract syntax tree

SYNOPSIS

Filter flatten.pl, adopted from pandoc scripting documentation, 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 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 from Python to modern Perl.

COPYRIGHT AND LICENSE

Copyright 2014- Jakob Voß

GNU General Public License, Version 2

This module is heavily based on Pandoc by John MacFarlane.