lib/Pod/ParseLink.pm

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