xref: /openbsd-src/gnu/usr.bin/perl/cpan/podlators/lib/Pod/ParseLink.pm (revision ae3cb403620ab940fbaabb3055fac045a63d56b7) 
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
22package Pod::ParseLink;
23
24use 5.006;
25use strict;
26use warnings;
27
28use vars qw(@EXPORT @ISA $VERSION);
29
30use Exporter;
31@ISA    = qw(Exporter);
32@EXPORT = qw(parselink);
33
34$VERSION = '4.07';
35
36##############################################################################
37# Implementation
38##############################################################################
39
40# Parse the name and section portion of a link into a name and section.
41sub _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.
66sub _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).
82sub 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.
1141;
115__END__
116
117=head1 NAME
118
119Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text
120
121=for stopwords
122markup 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
132This module only provides a single function, parselink(), which takes the
133text of an LE<lt>E<gt> formatting code and parses it.  It returns the
134anchor text for the link (if any was given), the anchor text possibly
135inferred from the name and section, the name or URL, the section if any,
136and the type of link.  The type will be one of C<url>, C<pod>, or C<man>,
137indicating a URL, a link to a POD page, or a link to a Unix manual page.
138
139Parsing is implemented per L<perlpodspec>.  For backward compatibility,
140links where there is no section and name contains spaces, or links where the
141entirety of the link (except for the anchor text if given) is enclosed in
142double-quotes are interpreted as links to a section (LE<lt>/sectionE<gt>).
143
144The 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
150The name may contain embedded EE<lt>E<gt> and ZE<lt>E<gt> formatting codes,
151and the section, anchor text, and inferred anchor text may contain any
152formatting codes.  Any double quotes around the section are removed as part
153of the parsing, as is any leading or trailing whitespace.
154
155If the text of the LE<lt>E<gt> escape is entirely enclosed in double
156quotes, it's interpreted as a link to a section for backward
157compatibility.
158
159No attempt is made to resolve formatting codes.  This must be done after
160calling parselink() (since EE<lt>E<gt> formatting codes can be used to
161escape characters that would otherwise be significant to the parser and
162resolving them before parsing would result in an incorrect parse of a
163formatting code like:
164
165    L<verticalE<verbar>barE<sol>slash>
166
167which should be interpreted as a link to the C<vertical|bar/slash> POD page
168and not as a link to the C<slash> section of the C<bar> POD page with an
169anchor text of C<vertical>.  Note that not only the anchor text will need to
170have formatting codes expanded, but so will the target of the link (to deal
171with EE<lt>E<gt> and ZE<lt>E<gt> formatting codes), and special handling of
172the section may be necessary depending on whether the translator wants to
173consider markup in sections to be significant when resolving links.  See
174L<perlpodspec> for more information.
175
176=head1 SEE ALSO
177
178L<Pod::Parser>
179
180The current version of this module is always available from its web site at
181L<http://www.eyrie.org/~eagle/software/podlators/>.
182
183=head1 AUTHOR
184
185Russ Allbery <rra@cpan.org>.
186
187=head1 COPYRIGHT AND LICENSE
188
189Copyright 2001, 2008, 2009 Russ Allbery <rra@cpan.org>.
190
191This program is free software; you may redistribute it and/or modify it
192under the same terms as Perl itself.
193
194=cut
195