1Pod::ParseUtils(3)    User Contributed Perl Documentation   Pod::ParseUtils(3)
2
3
4

NAME

6       Pod::ParseUtils - helpers for POD parsing and conversion
7

SYNOPSIS

9         use Pod::ParseUtils;
10
11         my $list = new Pod::List;
12         my $link = Pod::Hyperlink->new('Pod::Parser');
13

DESCRIPTION

15       NOTE: This module is considered legacy; modern Perl releases (5.31.1
16       and higher) are going to remove Pod-Parser from core and use
17       Pod::Simple for all things POD.
18
19       Pod::ParseUtils contains a few object-oriented helper packages for POD
20       parsing and processing (i.e. in POD formatters and translators).
21
22   Pod::List
23       Pod::List can be used to hold information about POD lists (written as
24       =over ... =item ... =back) for further processing.  The following
25       methods are available:
26
27       Pod::List->new()
28           Create a new list object. Properties may be specified through a
29           hash reference like this:
30
31             my $list = Pod::List->new({ -start => $., -indent => 4 });
32
33           See the individual methods/properties for details.
34
35       $list->file()
36           Without argument, retrieves the file name the list is in. This must
37           have been set before by either specifying -file in the new() method
38           or by calling the file() method with a scalar argument.
39
40       $list->start()
41           Without argument, retrieves the line number where the list started.
42           This must have been set before by either specifying -start in the
43           new() method or by calling the start() method with a scalar
44           argument.
45
46       $list->indent()
47           Without argument, retrieves the indent level of the list as
48           specified in "=over n". This must have been set before by either
49           specifying -indent in the new() method or by calling the indent()
50           method with a scalar argument.
51
52       $list->type()
53           Without argument, retrieves the list type, which can be an
54           arbitrary value, e.g. "OL", "UL", ... when thinking the HTML way.
55           This must have been set before by either specifying -type in the
56           new() method or by calling the type() method with a scalar
57           argument.
58
59       $list->rx()
60           Without argument, retrieves a regular expression for simplifying
61           the individual item strings once the list type has been determined.
62           Usage: E.g. when converting to HTML, one might strip the leading
63           number in an ordered list as "<OL>" already prints numbers itself.
64           This must have been set before by either specifying -rx in the
65           new() method or by calling the rx() method with a scalar argument.
66
67       $list->item()
68           Without argument, retrieves the array of the items in this list.
69           The items may be represented by any scalar.  If an argument has
70           been given, it is pushed on the list of items.
71
72       $list->parent()
73           Without argument, retrieves information about the parent holding
74           this list, which is represented as an arbitrary scalar.  This must
75           have been set before by either specifying -parent in the new()
76           method or by calling the parent() method with a scalar argument.
77
78       $list->tag()
79           Without argument, retrieves information about the list tag, which
80           can be any scalar.  This must have been set before by either
81           specifying -tag in the new() method or by calling the tag() method
82           with a scalar argument.
83
84   Pod::Hyperlink
85       Pod::Hyperlink is a class for manipulation of POD hyperlinks. Usage:
86
87         my $link = Pod::Hyperlink->new('alternative text|page/"section in page"');
88
89       The Pod::Hyperlink class is mainly designed to parse the contents of
90       the "L<...>" sequence, providing a simple interface for accessing the
91       different parts of a POD hyperlink for further processing. It can also
92       be used to construct hyperlinks.
93
94       Pod::Hyperlink->new()
95           The new() method can either be passed a set of key/value pairs or a
96           single scalar value, namely the contents of a "L<...>" sequence. An
97           object of the class "Pod::Hyperlink" is returned. The value "undef"
98           indicates a failure, the error message is stored in $@.
99
100       $link->parse($string)
101           This method can be used to (re)parse a (new) hyperlink, i.e. the
102           contents of a "L<...>" sequence. The result is stored in the
103           current object.  Warnings are stored in the warnings property.
104           E.g. sections like "L<open(2)>" are deprecated, as they do not
105           point to Perl documents. "L<DBI::foo(3p)>" is wrong as well, the
106           manpage section can simply be dropped.
107
108       $link->markup($string)
109           Set/retrieve the textual value of the link. This string contains
110           special markers "P<>" and "Q<>" that should be expanded by the
111           translator's interior sequence expansion engine to the formatter-
112           specific code to highlight/activate the hyperlink. The details have
113           to be implemented in the translator.
114
115       $link->text()
116           This method returns the textual representation of the hyperlink as
117           above, but without markers (read only). Depending on the link type
118           this is one of the following alternatives (the + and * denote the
119           portions of the text that are marked up):
120
121             +perl+                    L<perl>
122             *$|* in +perlvar+         L<perlvar/$|>
123             *OPTIONS* in +perldoc+    L<perldoc/"OPTIONS">
124             *DESCRIPTION*             L<"DESCRIPTION">
125
126       $link->warning()
127           After parsing, this method returns any warnings encountered during
128           the parsing process.
129
130       $link->file()
131       $link->line()
132           Just simple slots for storing information about the line and the
133           file the link was encountered in. Has to be filled in manually.
134
135       $link->page()
136           This method sets or returns the POD page this link points to.
137
138       $link->node()
139           As above, but the destination node text of the link.
140
141       $link->alttext()
142           Sets or returns an alternative text specified in the link.
143
144       $link->type()
145           The node type, either "section" or "item". As an unofficial type,
146           there is also "hyperlink", derived from e.g. "L<http://perl.com>"
147
148       $link->link()
149           Returns the link as contents of "L<>". Reciprocal to parse().
150
151   Pod::Cache
152       Pod::Cache holds information about a set of POD documents, especially
153       the nodes for hyperlinks.  The following methods are available:
154
155       Pod::Cache->new()
156           Create a new cache object. This object can hold an arbitrary number
157           of POD documents of class Pod::Cache::Item.
158
159       $cache->item()
160           Add a new item to the cache. Without arguments, this method returns
161           a list of all cache elements.
162
163       $cache->find_page($name)
164           Look for a POD document named $name in the cache. Returns the
165           reference to the corresponding Pod::Cache::Item object or undef if
166           not found.
167
168   Pod::Cache::Item
169       Pod::Cache::Item holds information about individual POD documents, that
170       can be grouped in a Pod::Cache object.  It is intended to hold
171       information about the hyperlink nodes of POD documents.  The following
172       methods are available:
173
174       Pod::Cache::Item->new()
175           Create a new object.
176
177       $cacheitem->page()
178           Set/retrieve the POD document name (e.g. "Pod::Parser").
179
180       $cacheitem->description()
181           Set/retrieve the POD short description as found in the "=head1
182           NAME" section.
183
184       $cacheitem->path()
185           Set/retrieve the POD file storage path.
186
187       $cacheitem->file()
188           Set/retrieve the POD file name.
189
190       $cacheitem->nodes()
191           Add a node (or a list of nodes) to the document's node list. Note
192           that the order is kept, i.e. start with the first node and end with
193           the last.  If no argument is given, the current list of nodes is
194           returned in the same order the nodes have been added.  A node can
195           be any scalar, but usually is a pair of node string and unique id
196           for the "find_node" method to work correctly.
197
198       $cacheitem->find_node($name)
199           Look for a node or index entry named $name in the object.  Returns
200           the unique id of the node (i.e. the second element of the array
201           stored in the node array) or undef if not found.
202
203       $cacheitem->idx()
204           Add an index entry (or a list of them) to the document's index
205           list. Note that the order is kept, i.e. start with the first node
206           and end with the last.  If no argument is given, the current list
207           of index entries is returned in the same order the entries have
208           been added.  An index entry can be any scalar, but usually is a
209           pair of string and unique id.
210

AUTHOR

212       Please report bugs using <http://rt.cpan.org>.
213
214       Marek Rouchal <marekr@cpan.org>, borrowing a lot of things from pod2man
215       and pod2roff as well as other POD processing tools by Tom Christiansen,
216       Brad Appleton and Russ Allbery.
217
218       Pod::ParseUtils is part of the Pod::Parser distribution.
219

SEE ALSO

221       pod2man, pod2roff, Pod::Parser, Pod::Checker, pod2html
222
223
224
225perl v5.36.0                      2022-07-22                Pod::ParseUtils(3)
Impressum