1Pod::ParseUtils(3pm) Perl Programmers Reference Guide Pod::ParseUtils(3pm)
2
6 Pod::ParseUtils - helpers for POD parsing and conversion
7
9 use Pod::ParseUtils;
10 my $list = new Pod::List;
12 my $link = Pod::Hyperlink->new('Pod::Parser');
13
15 Pod::ParseUtils contains a few object-oriented helper packages for POD
16 parsing and processing (i.e. in POD formatters and translators).
17 Pod::List
19 Pod::List can be used to hold information about POD lists (written as
21 =over ... =item ... =back) for further processing. The following meth‐
22 ods are available:
23 Pod::List->new()
25 Create a new list object. Properties may be specified through a
26 hash reference like this:
27 my $list = Pod::List->new({ -start => $., -indent => 4 });
29 See the individual methods/properties for details.
31 $list->file()
33 Without argument, retrieves the file name the list is in. This must
34 have been set before by either specifying -file in the new() method
35 or by calling the file() method with a scalar argument.
36 $list->start()
38 Without argument, retrieves the line number where the list started.
39 This must have been set before by either specifying -start in the
40 new() method or by calling the start() method with a scalar argu‐
41 ment.
42 $list->indent()
44 Without argument, retrieves the indent level of the list as speci‐
45 fied in "=over n". This must have been set before by either speci‐
46 fying -indent in the new() method or by calling the indent() method
47 with a scalar argument.
48 $list->type()
50 Without argument, retrieves the list type, which can be an arbi‐
51 trary value, e.g. "OL", "UL", ... when thinking the HTML way. This
52 must have been set before by either specifying -type in the new()
53 method or by calling the type() method with a scalar argument.
54 $list->rx()
56 Without argument, retrieves a regular expression for simplifying
57 the individual item strings once the list type has been determined.
58 Usage: E.g. when converting to HTML, one might strip the leading
59 number in an ordered list as "<OL>" already prints numbers itself.
60 This must have been set before by either specifying -rx in the
61 new() method or by calling the rx() method with a scalar argument.
62 $list->item()
64 Without argument, retrieves the array of the items in this list.
65 The items may be represented by any scalar. If an argument has
66 been given, it is pushed on the list of items.
67 $list->parent()
69 Without argument, retrieves information about the parent holding
70 this list, which is represented as an arbitrary scalar. This must
71 have been set before by either specifying -parent in the new()
72 method or by calling the parent() method with a scalar argument.
73 $list->tag()
75 Without argument, retrieves information about the list tag, which
76 can be any scalar. This must have been set before by either speci‐
77 fying -tag in the new() method or by calling the tag() method with
78 a scalar argument.
79 Pod::Hyperlink
81 Pod::Hyperlink is a class for manipulation of POD hyperlinks. Usage:
83 my $link = Pod::Hyperlink->new('alternative text⎪page/"section in page"');
85 The Pod::Hyperlink class is mainly designed to parse the contents of
87 the "L<...>" sequence, providing a simple interface for accessing the
88 different parts of a POD hyperlink for further processing. It can also
89 be used to construct hyperlinks.
90 Pod::Hyperlink->new()
92 The new() method can either be passed a set of key/value pairs or a
93 single scalar value, namely the contents of a "L<...>" sequence. An
94 object of the class "Pod::Hyperlink" is returned. The value "undef"
95 indicates a failure, the error message is stored in $@.
96 $link->parse($string)
98 This method can be used to (re)parse a (new) hyperlink, i.e. the
99 contents of a "L<...>" sequence. The result is stored in the cur‐
100 rent object. Warnings are stored in the warnings property. E.g.
101 sections like "L<open(2)>" are deprecated, as they do not point to
102 Perl documents. "L<DBI::foo(3p)>" is wrong as well, the manpage
103 section can simply be dropped.
104 $link->markup($string)
106 Set/retrieve the textual value of the link. This string contains
107 special markers "P<>" and "Q<>" that should be expanded by the
108 translator's interior sequence expansion engine to the formatter-
109 specific code to highlight/activate the hyperlink. The details have
110 to be implemented in the translator.
111 $link->text()
113 This method returns the textual representation of the hyperlink as
114 above, but without markers (read only). Depending on the link type
115 this is one of the following alternatives (the + and * denote the
116 portions of the text that are marked up):
117 +perl+ L<perl>
119 *$⎪* in +perlvar+ L<perlvar/$⎪>
120 *OPTIONS* in +perldoc+ L<perldoc/"OPTIONS">
121 *DESCRIPTION* L<"DESCRIPTION">
122 $link->warning()
124 After parsing, this method returns any warnings encountered during
125 the parsing process.
126 $link->file()
128 $link->line()
129 Just simple slots for storing information about the line and the
130 file the link was encountered in. Has to be filled in manually.
131 $link->page()
133 This method sets or returns the POD page this link points to.
134 $link->node()
136 As above, but the destination node text of the link.
137 $link->alttext()
139 Sets or returns an alternative text specified in the link.
140 $link->type()
142 The node type, either "section" or "item". As an unofficial type,
143 there is also "hyperlink", derived from e.g. "L<http://perl.com>"
144 $link->link()
146 Returns the link as contents of "L<>". Reciprocal to parse().
147 Pod::Cache
149 Pod::Cache holds information about a set of POD documents, especially
151 the nodes for hyperlinks. The following methods are available:
152 Pod::Cache->new()
154 Create a new cache object. This object can hold an arbitrary number
155 of POD documents of class Pod::Cache::Item.
156 $cache->item()
158 Add a new item to the cache. Without arguments, this method returns
159 a list of all cache elements.
160 $cache->find_page($name)
162 Look for a POD document named $name in the cache. Returns the ref‐
163 erence to the corresponding Pod::Cache::Item object or undef if not
164 found.
165 Pod::Cache::Item
167 Pod::Cache::Item holds information about individual POD documents, that
169 can be grouped in a Pod::Cache object. It is intended to hold informa‐
170 tion about the hyperlink nodes of POD documents. The following methods
171 are available:
172 Pod::Cache::Item->new()
174 Create a new object.
175 $cacheitem->page()
177 Set/retrieve the POD document name (e.g. "Pod::Parser").
178 $cacheitem->description()
180 Set/retrieve the POD short description as found in the "=head1
181 NAME" section.
182 $cacheitem->path()
184 Set/retrieve the POD file storage path.
185 $cacheitem->file()
187 Set/retrieve the POD file name.
188 $cacheitem->nodes()
190 Add a node (or a list of nodes) to the document's node list. Note
191 that the order is kept, i.e. start with the first node and end with
192 the last. If no argument is given, the current list of nodes is
193 returned in the same order the nodes have been added. A node can
194 be any scalar, but usually is a pair of node string and unique id
195 for the "find_node" method to work correctly.
196 $cacheitem->find_node($name)
198 Look for a node or index entry named $name in the object. Returns
199 the unique id of the node (i.e. the second element of the array
200 stored in the node arry) or undef if not found.
201 $cacheitem->idx()
203 Add an index entry (or a list of them) to the document's index
204 list. Note that the order is kept, i.e. start with the first node
205 and end with the last. If no argument is given, the current list
206 of index entries is returned in the same order the entries have
207 been added. An index entry can be any scalar, but usually is a
208 pair of string and unique id.
209
211 Please report bugs using <http://rt.cpan.org>.
212 Marek Rouchal <marekr@cpan.org>, borrowing a lot of things from pod2man
214 and pod2roff as well as other POD processing tools by Tom Christiansen,
215 Brad Appleton and Russ Allbery.
216
218 pod2man, pod2roff, Pod::Parser, Pod::Checker, pod2html
219perl v5.8.8 2001-09-21 Pod::ParseUtils(3pm)