cpan/podlators/lib/Pod/ParseLink.pm

   1 # Pod::ParseLink -- Parse an L<> formatting code in POD text.
   2 #
   3 # Copyright 2001, 2008, 2009, 2014 by Russ Allbery <rra@cpan.org>
   4 #
   5 # This program is free software; you may redistribute it and/or modify it
   6 # under the same terms as Perl itself.
   7 #
   8 # This module implements parsing of the text of an L<> formatting code as
   9 # defined in perlpodspec.  It should be suitable for any POD formatter.  It
  10 # exports only one function, parselink(), which returns the five-item parse
  11 # defined in perlpodspec.
  12 #
  13 # Perl core hackers, please note that this module is also separately
  14 # maintained outside of the Perl core as part of the podlators.  Please send
  15 # me any patches at the address above in addition to sending them to the
  16 # standard Perl mailing lists.
  17
  18 ##############################################################################
  19 # Modules and declarations
  20 ##############################################################################
  21
  22 package Pod::ParseLink;
  23
  24 use 5.006;
  25 use strict;
  26 use warnings;
  27
  28 use vars qw(@EXPORT @ISA $VERSION);
  29
  30 use Exporter;
  31 @ISA    = qw(Exporter);
  32 @EXPORT = qw(parselink);
  33
  34 $VERSION = '4.06';
  35
  36 ##############################################################################
  37 # Implementation
  38 ##############################################################################
  39
  40 # Parse the name and section portion of a link into a name and section.
  41 sub _parse_section {
  42     my ($link) = @_;
  43     $link =~ s/^\s+//;
  44     $link =~ s/\s+$//;
  45
  46     # If the whole link is enclosed in quotes, interpret it all as a section
  47     # even if it contains a slash.
  48     return (undef, $1) if ($link =~ /^"\s*(.*?)\s*"$/);
  49
  50     # Split into page and section on slash, and then clean up quoting in the
  51     # section.  If there is no section and the name contains spaces, also
  52     # guess that it's an old section link.
  53     my ($page, $section) = split (/\s*\/\s*/, $link, 2);
  54     $section =~ s/^"\s*(.*?)\s*"$/$1/ if $section;
  55     if ($page && $page =~ / / && !defined ($section)) {
  56         $section = $page;
  57         $page = undef;
  58     } else {
  59         $page = undef unless $page;
  60         $section = undef unless $section;
  61     }
  62     return ($page, $section);
  63 }
  64
  65 # Infer link text from the page and section.
  66 sub _infer_text {
  67     my ($page, $section) = @_;
  68     my $inferred;
  69     if ($page && !$section) {
  70         $inferred = $page;
  71     } elsif (!$page && $section) {
  72         $inferred = '"' . $section . '"';
  73     } elsif ($page && $section) {
  74         $inferred = '"' . $section . '" in ' . $page;
  75     }
  76     return $inferred;
  77 }
  78
  79 # Given the contents of an L<> formatting code, parse it into the link text,
  80 # the possibly inferred link text, the name or URL, the section, and the type
  81 # of link (pod, man, or url).
  82 sub parselink {
  83     my ($link) = @_;
  84     $link =~ s/\s+/ /g;
  85     my $text;
  86     if ($link =~ /\|/) {
  87         ($text, $link) = split (/\|/, $link, 2);
  88     }
  89     if ($link =~ /\A\w+:[^:\s]\S*\Z/) {
  90         my $inferred;
  91         if (defined ($text) && length ($text) > 0) {
  92             return ($text, $text, $link, undef, 'url');
  93         } else {
  94             return ($text, $link, $link, undef, 'url');
  95         }
  96     } else {
  97         my ($name, $section) = _parse_section ($link);
  98         my $inferred;
  99         if (defined ($text) && length ($text) > 0) {
 100             $inferred = $text;
 101         } else {
 102             $inferred = _infer_text ($name, $section);
 103         }
 104         my $type = ($name && $name =~ /\(\S*\)/) ? 'man' : 'pod';
 105         return ($text, $inferred, $name, $section, $type);
 106     }
 107 }
 108
 109 ##############################################################################
 110 # Module return value and documentation
 111 ##############################################################################
 112
 113 # Ensure we evaluate to true.
 114 1;
 115 __END__
 116
 117 =head1 NAME
 118
 119 Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text
 120
 121 =for stopwords
 122 markup Allbery URL
 123
 124 =head1 SYNOPSIS
 125
 126     use Pod::ParseLink;
 127     my $link = get_link();
 128     my ($text, $inferred, $name, $section, $type) = parselink($link);
 129
 130 =head1 DESCRIPTION
 131
 132 This module only provides a single function, parselink(), which takes the
 133 text of an LE<lt>E<gt> formatting code and parses it.  It returns the
 134 anchor text for the link (if any was given), the anchor text possibly
 135 inferred from the name and section, the name or URL, the section if any,
 136 and the type of link.  The type will be one of C<url>, C<pod>, or C<man>,
 137 indicating a URL, a link to a POD page, or a link to a Unix manual page.
 138
 139 Parsing is implemented per L<perlpodspec>.  For backward compatibility,
 140 links where there is no section and name contains spaces, or links where the
 141 entirety of the link (except for the anchor text if given) is enclosed in
 142 double-quotes are interpreted as links to a section (LE<lt>/sectionE<gt>).
 143
 144 The inferred anchor text is implemented per L<perlpodspec>:
 145
 146     L<name>         =>  L<name|name>
 147     L</section>     =>  L<"section"|/section>
 148     L<name/section> =>  L<"section" in name|name/section>
 149
 150 The name may contain embedded EE<lt>E<gt> and ZE<lt>E<gt> formatting codes,
 151 and the section, anchor text, and inferred anchor text may contain any
 152 formatting codes.  Any double quotes around the section are removed as part
 153 of the parsing, as is any leading or trailing whitespace.
 154
 155 If the text of the LE<lt>E<gt> escape is entirely enclosed in double
 156 quotes, it's interpreted as a link to a section for backward
 157 compatibility.
 158
 159 No attempt is made to resolve formatting codes.  This must be done after
 160 calling parselink() (since EE<lt>E<gt> formatting codes can be used to
 161 escape characters that would otherwise be significant to the parser and
 162 resolving them before parsing would result in an incorrect parse of a
 163 formatting code like:
 164
 165     L<verticalE<verbar>barE<sol>slash>
 166
 167 which should be interpreted as a link to the C<vertical|bar/slash> POD page
 168 and not as a link to the C<slash> section of the C<bar> POD page with an
 169 anchor text of C<vertical>.  Note that not only the anchor text will need to
 170 have formatting codes expanded, but so will the target of the link (to deal
 171 with EE<lt>E<gt> and ZE<lt>E<gt> formatting codes), and special handling of
 172 the section may be necessary depending on whether the translator wants to
 173 consider markup in sections to be significant when resolving links.  See
 174 L<perlpodspec> for more information.
 175
 176 =head1 SEE ALSO
 177
 178 L<Pod::Parser>
 179
 180 The current version of this module is always available from its web site at
 181 L<http://www.eyrie.org/~eagle/software/podlators/>.
 182
 183 =head1 AUTHOR
 184
 185 Russ Allbery <rra@cpan.org>.
 186
 187 =head1 COPYRIGHT AND LICENSE
 188
 189 Copyright 2001, 2008, 2009 Russ Allbery <rra@cpan.org>.
 190
 191 This program is free software; you may redistribute it and/or modify it
 192 under the same terms as Perl itself.
 193
 194 =cut