1 # Pod::ParseLink -- Parse an L<> formatting code in POD text.
3 # Copyright 2001 by Russ Allbery <rra@stanford.edu>
5 # This program is free software; you may redistribute it and/or modify it
6 # under the same terms as Perl itself.
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.
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.
18 ##############################################################################
19 # Modules and declarations
20 ##############################################################################
22 package Pod::ParseLink;
27 use vars qw(@EXPORT @ISA $VERSION);
31 @EXPORT = qw(parselink);
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.
39 ##############################################################################
41 ##############################################################################
43 # Parse the name and section portion of a link into a name and section.
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*"$/);
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)) {
62 $page = undef unless $page;
63 $section = undef unless $section;
65 return ($page, $section);
68 # Infer link text from the page and section.
70 my ($page, $section) = @_;
72 if ($page && !$section) {
74 } elsif (!$page && $section) {
75 $inferred = '"' . $section . '"';
76 } elsif ($page && $section) {
77 $inferred = '"' . $section . '" in ' . $page;
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).
88 if ($link =~ /\A\w+:[^:\s]\S*\Z/) {
89 return (undef, $link, $link, undef, 'url');
93 ($text, $link) = split (/\|/, $link, 2);
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);
103 ##############################################################################
104 # Module return value and documentation
105 ##############################################################################
107 # Ensure we evaluate to true.
113 Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text
118 my ($text, $inferred, $name, $section, $type) = parselink ($link);
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.
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>).
134 The inferred anchor text is implemented per L<perlpodspec>:
136 L<name> => L<name|name>
137 L</section> => L<"section"|/section>
138 L<name/section> => L<"section" in name|name/section>
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.
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.
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
154 L<verticalE<verbar>barE<sol>slash>
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.
169 The current version of this module is always available from its web site at
170 L<http://www.eyrie.org/~eagle/software/podlators/>.
174 Russ Allbery <rra@stanford.edu>.
176 =head1 COPYRIGHT AND LICENSE
178 Copyright 2001 by Russ Allbery <rra@stanford.edu>.
180 This program is free software; you may redistribute it and/or modify it
181 under the same terms as Perl itself.