App::Po...rseLinks(3)

💖 NAME 💖

Okay bestie, this is the User Contributed Perl Documentation page for App::PodLinkCheck::ParseLinks(3). The manual name is App::PodLinkCheck::ParseLinks — the header shows it as App::Po...rseLinks(3) — and its whole thing is to parse out POD L<> links. Slay.

✨ SYNOPSIS ✨

use App::PodLinkCheck::ParseLinks;

🧚 CLASS HIERARCHY 🧚

   Pod::Simple
     App::PodLinkCheck::ParseSections
       App::PodLinkCheck::ParseLinks

🌸 DESCRIPTION 🌸

This is a POD parser that App::PodLinkCheck uses to find L<> links and section names in a document. Its behavior is specific to PodLinkCheck, but bestie, it might have other uses too — no cap.

Section names are recorded exactly as per the superclass App::PodLinkCheck::ParseSections. This subclass also records L<> links.

Links live in an array (and sections live in a hash) instead of callbacks or similar, because PodLinkCheck does its analysis at the end of a document. Why? Because internal links will be satisfied by section names that might show up late in the document, and the full list of section names gets used to suggest likely candidates for a broken link. It's giving end-of-document main character energy, honestly.

🛠️ FUNCTIONS 🛠️

$parser = App::PodLinkCheck::ParseLinks->new($options_hashref)

Create and return a new parser object. (See superclass App::PodLinkCheck::ParseSections on POD whining options.)

$parser->parse_file($filename)

Parse the pod from $filename. All the various Pod::Simple parse input styles can be used too.

$aref = $parser->links_arrayref()

Return an arrayref of L<> links seen by $parser. Each array element is a 5-element arrayref:

[ $type,       # L<> attribute, eg. 'pod' or 'man'
  $to,         # L<> attribute, whitespace collapsed, or undef
  $section,    # L<> attribute or undef
  $linenum,    # integer, first line 1
  $column      # integer, first column 1
]

So for example:

my $links_arrayref = $parser->links_arrayref;
foreach my $link (@$links_arrayref) {
  my ($type, $to, $section, $linenum, $column) = @$link;
  ...

$type, $to and $section are the type, to and section attributes from Pod::Simple. An internal link has $to = undef. An external link with no section has $section = undef.

$to and $section are mildly normalized: whitespace gets collapsed to a single space each, and leading/trailing whitespace gets removed. The belief is that's mostly how the pod formatters end up treating target names for linking purposes. (That sort of treatment is the intention here.) Usually $to won't have any whitespace, since it's a module name etc.

$linenum and $column are the location of the L<> in the input file. Pod::Simple normally only gives the paragraph start line. Some gambits here give more resolution, since it's helpful to show the exact place in a paragraph with several links.

The links accumulate everything seen by $parser. No attention is paid to any Document start etc. Usually a new App::PodLinkCheck::ParseLinks will be used for each file.

Accuracy note, bestie: the accuracy of $linenum and $column presently depends on seeing X<> codes, so if you're subclassing or similar, don't nix_X_codes(). 💅

🔗 SEE ALSO 🔗

App::PodLinkCheck, App::PodLinkCheck::ParseSections

🏠 HOME PAGE 🏠

http://user42.tuxfamily.org/podlinkcheck/index.html

📜 LICENSE 📜

Copyright 2010, 2011, 2012, 2013, 2016 Kevin Ryde.

PodLinkCheck is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

PodLinkCheck is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with PodLinkCheck. If not, see http://www.gnu.org/licenses/.

---

That's the whole page, bestie! It's from perl v5.32.1, dated 2022-01-14, and the manual name is App::Po...rseLinks(3) — go off 💅✨.