Pod::ParseLink(3pm)

📦
version 5.42.3 · 9 versions
, in alpine 3.24

🌸 NAME 🌸

okay so bestie, welcome to the Pod::ParseLink(3pm) page from the Perl Programmers Reference Guide ✨ — and this module is here for one very specific job: parsing an L<> formatting code in POD text. that’s the name, that’s the vibe, no cap. 💅

✨ SYNOPSIS ✨

here’s the whole group-chat entry point, literally:

    use Pod::ParseLink;
    my $link = get_link();
    my ($text, $inferred, $name, $section, $type) = parselink($link);

slay. that’s it. 🫶

💖 DESCRIPTION 💖

okay so this module is not a whole toolbox, bestie: it only provides a single function, parselink(), and its whole job is taking the text of an L<> formatting code and parsing it. periodt.

here’s what comes back from parselink():

  1. the anchor text for the link, if any was given
  2. the anchor text possibly inferred from the name and section
  3. the name or URL
  4. the section, if any
  5. the type of link

the type will be one of "url", "pod", or "man", indicating a URL, a link to a POD page, or a link to a Unix manual page. iconic little enum moment. 👑

parsing is implemented per perlpodspec. for backward compatibility, there are two legacy little situations that get interpreted as links to a section (L</section>):

  • links where there is no section and the name contains spaces
  • links where the entirety of the link (except for the anchor text if given) is enclosed in double-quotes

the inferred anchor text is implemented per perlpodspec too, and here’s the exact mapping:

L<name>         =>  L<name|name>
L</section>     =>  L<"section"|/section>
L<name/section> =>  L<"section" in name|name/section>

the name may contain embedded E<> and Z<> formatting codes, and the section, anchor text, and inferred anchor text may contain any formatting codes. any double quotes around the section are removed as part of the parsing, as is any leading or trailing whitespace. cleanup era. 🧚

if the text of the L<> escape is entirely enclosed in double quotes, it’s interpreted as a link to a section for backward compatibility. yes, another legacy vibe. we respect the lore. 💜

⚠️ big important caveat: no attempt is made to resolve formatting codes. this must be done after calling parselink().

why? because E<> formatting codes can be used to escape characters that would otherwise be significant to the parser, and resolving them before parsing would result in an incorrect parse of a formatting code like:

L<verticalE<verbar>barE<sol>slash>

which should be interpreted as a link to the "vertical|bar/slash" POD page and not as a link to the "slash" section of the "bar" POD page with an anchor text of "vertical". the parser is doing math, not vibes. 😭

and note: it’s not only the anchor text that will need to have formatting codes expanded — the target of the link will need it too (to deal with E<> and Z<> formatting codes), and special handling of the section may be necessary depending on whether the translator wants to consider markup in sections to be significant when resolving links. check perlpodspec for more information, bestie. 🦋

🫶 AUTHOR 🫶

this absolute icon is Russ Allbery <rra@cpan.org>. 💖

Copyright 2001, 2008, 2009, 2014, 2018-2019, 2022, 2024 Russ Allbery <rra@cpan.org>

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

legal tea, served fresh. ☕✨

🦋 SEE ALSO 🦋

  • Pod::Parser

the current version of this module is always available from its web site at <https://www.eyrie.org/~eagle/software/podlators/>. go click, bestie. 🌈

okay bye bestie 💋 — this page is Pod::ParseLink(3pm) from perl v5.42.3, dated 2026-11-03. mwah! 🌸

📦 where this page comes from