Pandoc::Walker(3pm)

💖 Pandoc::Walker — the Pandoc::Walker(3pm) glow-up 💖

okay so this is a page from the User Contributed Perl Documentation, and bestie, it's a whole module for walking through Pandoc documents. 🚶♀️✨

---

🌸 NAME 🌸

Pandoc::Walker — utility functions to process Pandoc documents 🦋

---

✨ SYNOPSIS ✨

use Pandoc::Walker;
use Pandoc::Elements qw(pandoc_json);

my $ast = pandoc_json(<>);

# extract all links and image URLs
my $links = query $ast, 'Link|Image' => sub { $_->url };

# print all links and image URLs
walk $ast, 'Link|Image' => sub { say $_->url };

# remove all links
transform $ast, sub {
    return ($_->name eq 'Link' ? [] : ());
};

# replace all links by their link text angle brackets
use Pandoc::Elements 'Str';
transform $ast, Link => sub {
    return (Str " < ", $_->content->[0], Str " > ");
};

---

🎀 DESCRIPTION 🎀

This module hands you a little toolkit of utility functions to traverse the abstract syntax tree (AST) of a pandoc document. (If you wanna know all about AST elements themselves, go read Pandoc::Elements, that's its whole thing 💅)

⚠️ lowkey important, bestie: Document elements get passed to action functions by reference, so like… don't shoot yourself in the foot by trying to directly modify the element. That's the foot-shooting move. don't do it. 🙈

And traversing a single element isn't reliable neither, so if you need to do that, put the element in an array reference. Fr fr. For instance, to replace links in headers only by their link text content:

transform $ast, Header => sub {
    transform [ $_[0] ], Link => sub { # make an array
        return $_[0]->content;         # is an array
    };
};

alsooo shoutout to Pandoc::Filter, which gives you an object oriented interface to transformations if that's more your vibe. 👑

---

🧚 FUNCTIONS 🧚

💫 action ( [ $selector => ] $code [, @arguments ] )

💫 action ( { $selector => $code, ... } [, @arguments ] )

Returns an action function to process document elements. 🫶

---

💫 walk( $ast, ... )

Walks an abstract syntax tree and calls an action on every element, or on every element of the given name(s). Any additional arguments get passed along to the action too. 🚶♀️✨

the one rule: if and only if the action function returns \undef, the current element is not traversed further. That's the whole trigger, no cap.

See also the function pandoc_walk exported by Pandoc::Filter. 🌈

---

💫 query( $ast, ... )

Walks an abstract syntax tree and applies one or multiple query functions to extract results. The query function is expected to return a list or \undef. The combined query result comes back to you as an array reference. 📦✨

For instance, the string method of Pandoc::Elements is implemented like this:

join '', @{
    query( $ast, {
        'Str|Code|Math'   => sub { $_->content },
        'LineBreak|Space' => sub { ' ' }
    } );

---

💫 transform( $ast, ... )

Walks an abstract syntax tree and applies an action on every element, or every element of given name(s), so you can either:

• keep it — if the action returns undef or \undef 💖
• remove it — if it returns an empty array reference 💀
• replace it with one or more elements — returned by array reference, or as a single value 🌟

See also the function pandoc_filter exported by Pandoc::Filter. 🎀

---

👑 COPYRIGHT AND LICENSE 👑

Copyright 2014- Jakob Voß

GNU General Public License, Version 2

This module is heavily based on Pandoc by John MacFarlane. 🙇♀️

---

🌈 SEE ALSO 🌈

• Haskell module Text.Pandoc.Walk <http://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Walk.html> for the original.

---

and that's the whole page, bestie ✨ this lil doc drop is from perl v5.38.2, dated 2024-08-03. go forth and walk those trees 💅🌳💖