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.

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 document content AST (without metadata elements). Implicitly sets binmode UTF-8 for STDOUT.

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. This function is roughly equivalent to

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

build_image( $element [, $filename ] )

Maps an element to an Image element with attributes from the given element. The attribute caption, if available, is transformed into image caption. This utility function is useful for filters that transform content to images. See graphviz, tikz, lilypond and similar filters in the examples.

This function is experimental and may be (re)move in a later version!

SEE ALSO

This module is a port of pandocfilters from Python to modern Perl.

Script pandocwalk, installed with this module, facilitates execution of pandoc_walk to traverse a document from command line.

COPYRIGHT AND LICENSE

Copyright 2014- Jakob Voß

GNU General Public License, Version 2

This module is heavily based on Pandoc by John MacFarlane.

cpanm Pandoc::Elements

perl -MCPAN -e shell
install Pandoc::Elements