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

AUTHOR

208       Please report bugs using <http://rt.cpan.org>.
209
210       Marek Rouchal <marekr@cpan.org>, borrowing a lot of things from pod2man
211       and pod2roff as well as other POD processing tools by Tom Christiansen,
212       Brad Appleton and Russ Allbery.
213

SEE ALSO

215       pod2man, pod2roff, Pod::Parser, Pod::Checker, pod2html
216
217
218
219perl v5.12.4                      2011-06-01              Pod::ParseUtils(3pm)
Impressum