/ 
podlinkcheck-15
River stage two • 2 direct dependents • 25 total dependents
/ App::PodLinkCheck::ParseLinks

NAME

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

SYNOPSIS

use App::PodLinkCheck::ParseLinks;

CLASS HIERARCHY

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

DESCRIPTION

This is a POD parser used by App::PodLinkCheck to find L<> links and section names in a document. Its behaviour is specific to PodLinkCheck but might have other use.

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

Links are recorded in an array (and sections in a hash) rather than callbacks or similar because PodLinkCheck does its analysis at the end of a document. This is since internal links will be satisfied by section names which might be late in the document, and the full list of section names is used to suggest likely candidates for a broken link.

FUNCTIONS

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.

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 by collapsing whitespace to a single space each and removing leading and trailing whitespace. Believe that's mostly how the pod formatters end up treating target names for linking purposes. (That sort of treatment being the intention here.) Usually $to won't have any whitespace (being 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.

The accuracy of $linenum and $column presently depend on seeing X<> codes, so if 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/>.