Scroll to navigation

Pandoc::Filter(3pm) User Contributed Perl Documentation Pandoc::Filter(3pm)

NAME

Pandoc::Filter - process Pandoc abstract syntax tree

SYNOPSIS

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;       # 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 <http://pandoc.org/> 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. Pandoc::Filter::Usage is used to print filter documentation if called with command line argument "--help", "-h", or "-?".

FILTER MODULES

SEE ALSO

This module is a port of pandocfilters <https://github.com/jgm/pandocfilters> from Python to modern Perl.

COPYRIGHT AND LICENSE

Copyright 2014- Jakob Voss

GNU General Public License, Version 2

This module is heavily based on Pandoc by John MacFarlane.

2017-03-31 perl v5.24.1