App::PodLinkCheck::ParseLinks(3pm)

1App::PodLinkCheck::ParsUesLeirnkCso(n3t)ributed Perl DocAupmpe:n:tPaotdiLoinnkCheck::ParseLinks(3)
2
3
4

NAME

6       App::PodLinkCheck::ParseLinks -- parse out POD L<> links
7

SYNOPSIS

9        use App::PodLinkCheck::ParseLinks;
10

CLASS HIERARCHY

12           Pod::Simple
13             App::PodLinkCheck::ParseSections
14               App::PodLinkCheck::ParseLinks
15

DESCRIPTION

17       This is a POD parser used by "App::PodLinkCheck" to find "L<>" links
18       and section names in a document.  Its behaviour is specific to
19       PodLinkCheck but might have other use.
20
21       Section names are recorded as per the superclass
22       "App::PodLinkCheck::ParseSections".  This subclass records "L<>" links
23       too.
24
25       Links are recorded in an array (and sections in a hash) rather than
26       callbacks or similar because PodLinkCheck does its analysis at the end
27       of a document.  This is since internal links will be satisfied by
28       section names which might be late in the document, and the full list of
29       section names is used to suggest likely candidates for a broken link.
30

FUNCTIONS

32       "$parser = App::PodLinkCheck::ParseLinks->new($options_hashref)"
33           Create and return a new parser object.
34
35           (See superclass App::PodLinkCheck::ParseSections on POD whining
36           options.)
37
38       "$parser->parse_file($filename)"
39           Parse the pod from $filename.  All the various "Pod::Simple" parse
40           input styles can be used too.
41
42       "$aref = $parser->links_arrayref()"
43           Return an arrayref of "L<>" links seen by $parser.  Each array
44           element is a 5-element arrayref
45
46                   [ $type,       # L<> attribute, eg. 'pod' or 'man'
47                     $to,         # L<> attribute, whitespace collapsed, or undef
48                     $section,    # L<> attribute or undef
49                     $linenum,    # integer, first line 1
50                     $column      # integer, first column 1
51                   ]
52
53           So for example
54
55               my $links_arrayref = $parser->links_arrayref;
56               foreach my $link (@$links_arrayref) {
57                 my ($type, $to, $section, $linenum, $column) = @$link;
58                 ...
59
60           $type, $to and $section are the "type", "to" and "section"
61           attributes from "Pod::Simple".  An internal link has "$to = undef".
62           An external link with no section has "$section = undef".
63
64           $to and $section are mildly normalized by collapsing whitespace to
65           a single space each and removing leading and trailing whitespace.
66           Believe that's mostly how the pod formatters end up treating target
67           names for linking purposes.  (That sort of treatment being the
68           intention here.)  Usually $to won't have any whitespace (being a
69           module name etc).
70
71           $linenum and $column are the location of the "L<>" in the input
72           file.  "Pod::Simple" normally only gives the paragraph start line.
73           Some gambits here give more resolution since it's helpful to show
74           the exact place in a paragraph with several links.
75
76           The links accumulate everything seen by $parser.  No attention is
77           paid to any "Document" start etc.  Usually a new
78           "App::PodLinkCheck::ParseLinks" will be used for each file.
79
80           The accuracy of $linenum and $column presently depend on seeing
81           "X<>" codes, so if subclassing or similar don't nix_X_codes().
82

HOME PAGE

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

LICENSE

90       Copyright 2010, 2011, 2012, 2013, 2016 Kevin Ryde
91
92       PodLinkCheck is free software; you can redistribute it and/or modify it
93       under the terms of the GNU General Public License as published by the
94       Free Software Foundation; either version 3, or (at your option) any
95       later version.
96
97       PodLinkCheck is distributed in the hope that it will be useful, but
98       WITHOUT ANY WARRANTY; without even the implied warranty of
99       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
100       General Public License for more details.
101
102       You should have received a copy of the GNU General Public License along
103       with PodLinkCheck.  If not, see <http://www.gnu.org/licenses/>.
104
105
106
107perl v5.36.0                      2023-01-20  App::PodLinkCheck::ParseLinks(3)