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