Pandoc::Filter(3pm)

💖 Pandoc::Filter(3pm) 💖

okay bestie, welcome to your new fave Perl module, Pandoc::Filter — it's part of the User Contributed Perl Documentation crew, and it's literally here to process Pandoc abstract syntax tree 🌳✨

---

✨ NAME ✨

Pandoc::Filter — process Pandoc abstract syntax tree, no big deal, just your main character module 💅

---

🌸 SYNOPSIS 🌸

okay so picture this: there's a Filter called flatten.pl, adopted from the pandoc scripting documentation at http://pandoc.org/scripting.html, and what it does is convert level 2+ headers into regular paragraphs. iconic behavior tbh:

use Pandoc::Filter;
use Pandoc::Elements;

pandoc_filter Header => sub {
    return unless $_->level >= 2;       # keep
    return Para [ Emph $_->content ];   # replace
};

and then you apply this filter on a Markdown file like this, bestie:

pandoc --filter flatten.pl -t markdown < input.md

want even MORE filter inspo? gorg, go check out https://metacpan.org/pod/distribution/Pandoc-Elements/examples/ for more examples of filters 🫶

---

🦋 DESCRIPTION 🦋

so Pandoc::Filter provides tools to modify the abstract syntax tree (AST) of Pandoc http://pandoc.org/ documents. if you wanna know about the AST elements that filters can modify, that's Pandoc::Elements, go say hi to her 💜

the function interface (peep FUNCTIONS below) directly reads AST and format from STDIN and ARGV and prints the transformed AST to STDOUT. very demure, very direct ✨

the object oriented interface (that's the METHODS section, iykyk) requires you to do this little ritual:

my $filter = Pandoc::Filter->new( ... );  # create a filter object
$filter->apply( $ast, $format );          # pass it an AST for processing

and if you don't need the format parameter at all? bestie, consider using the interface provided by the module Pandoc::Walker instead. she's flexible like that, you can use her both ways:

transform $ast, ...;        # as function
$ast->transform( ... );     # or as method

---

💅 ACTIONS 💅

an action is a code reference that gets executed on matching document elements of an AST. the action gets passed a reference to the current element, the output format (which is the empty string by default), and the document metadata (an empty hash by default). and because the devs love us, 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 — and those three things mean modify, remove, or keep a traversed element in the AST. choose your fighter 🎀

---

👑 METHODS 👑

🍓 new( @actions | %actions )

create a new filter object with one or more actions (scroll up to ACTIONS if you forgot what those are 💀). if actions are given as a hash, the key values are used to check which elements to apply for, like:

Pandoc::Filter->new(
    Header                 => sub { ... },
    'Suscript|Superscript' => sub { ... }
)

🌈 apply( $ast [, $format [, $metadata ] ] )

apply all actions to a given abstract syntax tree (AST). bestie, listen: the AST is modified in place, and it's also returned for convenience (she's generous like that ✨). the additional arguments format and metadata are also passed to the action function. metadata is taken from the Document by default (that's if the AST is a Document root).

🧚 action

Return a code reference to call all actions. that's it, that's the whole vibe.

---

⭐ FUNCTIONS ⭐

the following functions are exported by default, no extra imports needed, we love a low-maintenance queen:

🎀 pandoc_filter( @actions | %actions )

read a single line of JSON from STDIN, apply actions on the document content, and print the resulting AST as a single line of JSON. and if the filter gets called with the command line argument --help, -h, or -?, then filter documentation gets printed instead. 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 https://github.com/jgm/pandocfilters from Python to modern Perl. glow up of the century, fr fr 💖

---

💜 COPYRIGHT AND LICENSE 💜

Copyright 2014- Jakob Voß

GNU General Public License, Version 2

this module is heavily based on Pandoc by John MacFarlane.

---

okay queen, that's the whole page. go forth and filter some ASTs, you've got this 🫶

that's a wrap bestie!! this lil doc lives in perl v5.38.2, dated 2024-08-03, and answers to the name Pandoc::Filter(3pm) 💅✨ bye pookie, go slay 🎀