NAME

Pandoc::Filter - process Pandoc abstract syntax tree

SYNOPSIS

The following 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;
        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 from Python to modern Perl. The module provide provides 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.

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 $_.

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).

FUNCTIONS

The following functions are exported by default.

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);
    say $ast->to_json;

pandoc_walk( @actions | %actions )

Read a single line of JSON from STDIN and walk down the AST.

stringify( $ast )

Walks the ast and returns concatenated string content, leaving out all formatting.

SEE ALSO

Script pandoc-walk installed with this module facilitates execution of pandoc_walk to traverse a document.

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