1Pod::InputObjects(3pm) Perl Programmers Reference Guide Pod::InputObjects(3pm)
2
6 Pod::InputObjects - objects representing POD input paragraphs,
7 commands, etc.
8
10 use Pod::InputObjects;
11
13 perl5.004, Carp
14
16 Nothing.
17
19 This module defines some basic input objects used by Pod::Parser when
20 reading and parsing POD text from an input source. The following
21 objects are defined:
22 package Pod::Paragraph
24 An object corresponding to a paragraph of POD input text. It may be
26 a plain paragraph, a verbatim paragraph, or a command paragraph
27 (see perlpod).
28 package Pod::InteriorSequence
30 An object corresponding to an interior sequence command from the
32 POD input text (see perlpod).
33 package Pod::ParseTree
35 An object corresponding to a tree of parsed POD text. Each "node"
37 in a parse-tree (or ptree) is either a text-string or a reference
38 to a Pod::InteriorSequence object. The nodes appear in the parse-
39 tree in the order in which they were parsed from left-to-right.
40 Each of these input objects are described in further detail in the
42 sections which follow.
43
45 An object representing a paragraph of POD input text. It has the
46 following methods/attributes:
47 Pod::Paragraph->new()
49 my $pod_para1 = Pod::Paragraph->new(-text => $text);
50 my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
51 -text => $text);
52 my $pod_para3 = new Pod::Paragraph(-text => $text);
53 my $pod_para4 = new Pod::Paragraph(-name => $cmd,
54 -text => $text);
55 my $pod_para5 = Pod::Paragraph->new(-name => $cmd,
56 -text => $text,
57 -file => $filename,
58 -line => $line_number);
59 This is a class method that constructs a "Pod::Paragraph" object and
61 returns a reference to the new paragraph object. It may be given one or
62 two keyword arguments. The "-text" keyword indicates the corresponding
63 text of the POD paragraph. The "-name" keyword indicates the name of
64 the corresponding POD command, such as "head1" or "item" (it should not
65 contain the "=" prefix); this is needed only if the POD paragraph
66 corresponds to a command paragraph. The "-file" and "-line" keywords
67 indicate the filename and line number corresponding to the beginning of
68 the paragraph
69 $pod_para->cmd_name()
71 my $para_cmd = $pod_para->cmd_name();
72 If this paragraph is a command paragraph, then this method will return
74 the name of the command (without any leading "=" prefix).
75 $pod_para->text()
77 my $para_text = $pod_para->text();
78 This method will return the corresponding text of the paragraph.
80 $pod_para->raw_text()
82 my $raw_pod_para = $pod_para->raw_text();
83 This method will return the raw text of the POD paragraph, exactly as
85 it appeared in the input.
86 $pod_para->cmd_prefix()
88 my $prefix = $pod_para->cmd_prefix();
89 If this paragraph is a command paragraph, then this method will return
91 the prefix used to denote the command (which should be the string "="
92 or "==").
93 $pod_para->cmd_separator()
95 my $separator = $pod_para->cmd_separator();
96 If this paragraph is a command paragraph, then this method will return
98 the text used to separate the command name from the rest of the
99 paragraph (if any).
100 $pod_para->parse_tree()
102 my $ptree = $pod_parser->parse_text( $pod_para->text() );
103 $pod_para->parse_tree( $ptree );
104 $ptree = $pod_para->parse_tree();
105 This method will get/set the corresponding parse-tree of the
107 paragraph's text.
108 $pod_para->file_line()
110 my ($filename, $line_number) = $pod_para->file_line();
111 my $position = $pod_para->file_line();
112 Returns the current filename and line number for the paragraph object.
114 If called in a list context, it returns a list of two elements: first
115 the filename, then the line number. If called in a scalar context, it
116 returns a string containing the filename, followed by a colon (':'),
117 followed by the line number.
118
120 An object representing a POD interior sequence command. It has the
121 following methods/attributes:
122 Pod::InteriorSequence->new()
124 my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
125 -ldelim => $delimiter);
126 my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd,
127 -ldelim => $delimiter);
128 my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd,
129 -ldelim => $delimiter,
130 -file => $filename,
131 -line => $line_number);
132 my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree);
134 my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree);
135 This is a class method that constructs a "Pod::InteriorSequence" object
137 and returns a reference to the new interior sequence object. It should
138 be given two keyword arguments. The "-ldelim" keyword indicates the
139 corresponding left-delimiter of the interior sequence (e.g. '<'). The
140 "-name" keyword indicates the name of the corresponding interior
141 sequence command, such as "I" or "B" or "C". The "-file" and "-line"
142 keywords indicate the filename and line number corresponding to the
143 beginning of the interior sequence. If the $ptree argument is given, it
144 must be the last argument, and it must be either string, or else an
145 array-ref suitable for passing to Pod::ParseTree::new (or it may be a
146 reference to a Pod::ParseTree object).
147 $pod_seq->cmd_name()
149 my $seq_cmd = $pod_seq->cmd_name();
150 The name of the interior sequence command.
152 $pod_seq->prepend()
154 $pod_seq->prepend($text);
155 $pod_seq1->prepend($pod_seq2);
156 Prepends the given string or parse-tree or sequence object to the
158 parse-tree of this interior sequence.
159 $pod_seq->append()
161 $pod_seq->append($text);
162 $pod_seq1->append($pod_seq2);
163 Appends the given string or parse-tree or sequence object to the parse-
165 tree of this interior sequence.
166 $pod_seq->nested()
168 $outer_seq = $pod_seq->nested || print "not nested";
169 If this interior sequence is nested inside of another interior
171 sequence, then the outer/parent sequence that contains it is returned.
172 Otherwise "undef" is returned.
173 $pod_seq->raw_text()
175 my $seq_raw_text = $pod_seq->raw_text();
176 This method will return the raw text of the POD interior sequence,
178 exactly as it appeared in the input.
179 $pod_seq->left_delimiter()
181 my $ldelim = $pod_seq->left_delimiter();
182 The leftmost delimiter beginning the argument text to the interior
184 sequence (should be "<").
185 $pod_seq->right_delimiter()
187 The rightmost delimiter beginning the argument text to the interior
188 sequence (should be ">").
189 $pod_seq->parse_tree()
191 my $ptree = $pod_parser->parse_text($paragraph_text);
192 $pod_seq->parse_tree( $ptree );
193 $ptree = $pod_seq->parse_tree();
194 This method will get/set the corresponding parse-tree of the interior
196 sequence's text.
197 $pod_seq->file_line()
199 my ($filename, $line_number) = $pod_seq->file_line();
200 my $position = $pod_seq->file_line();
201 Returns the current filename and line number for the interior sequence
203 object. If called in a list context, it returns a list of two
204 elements: first the filename, then the line number. If called in a
205 scalar context, it returns a string containing the filename, followed
206 by a colon (':'), followed by the line number.
207 Pod::InteriorSequence::DESTROY()
209 This method performs any necessary cleanup for the interior-sequence.
210 If you override this method then it is imperative that you invoke the
211 parent method from within your own method, otherwise interior-sequence
212 storage will not be reclaimed upon destruction!
213
215 This object corresponds to a tree of parsed POD text. As POD text is
216 scanned from left to right, it is parsed into an ordered list of text-
217 strings and Pod::InteriorSequence objects (in order of appearance). A
218 Pod::ParseTree object corresponds to this list of strings and
219 sequences. Each interior sequence in the parse-tree may itself contain
220 a parse-tree (since interior sequences may be nested).
221 Pod::ParseTree->new()
223 my $ptree1 = Pod::ParseTree->new;
224 my $ptree2 = new Pod::ParseTree;
225 my $ptree4 = Pod::ParseTree->new($array_ref);
226 my $ptree3 = new Pod::ParseTree($array_ref);
227 This is a class method that constructs a "Pod::Parse_tree" object and
229 returns a reference to the new parse-tree. If a single-argument is
230 given, it must be a reference to an array, and is used to initialize
231 the root (top) of the parse tree.
232 $ptree->top()
234 my $top_node = $ptree->top();
235 $ptree->top( $top_node );
236 $ptree->top( @children );
237 This method gets/sets the top node of the parse-tree. If no arguments
239 are given, it returns the topmost node in the tree (the root), which is
240 also a Pod::ParseTree. If it is given a single argument that is a
241 reference, then the reference is assumed to a parse-tree and becomes
242 the new top node. Otherwise, if arguments are given, they are treated
243 as the new list of children for the top node.
244 $ptree->children()
246 This method gets/sets the children of the top node in the parse-tree.
247 If no arguments are given, it returns the list (array) of children
248 (each of which should be either a string or a Pod::InteriorSequence.
249 Otherwise, if arguments are given, they are treated as the new list of
250 children for the top node.
251 $ptree->prepend()
253 This method prepends the given text or parse-tree to the current parse-
254 tree. If the first item on the parse-tree is text and the argument is
255 also text, then the text is prepended to the first item (not added as a
256 separate string). Otherwise the argument is added as a new string or
257 parse-tree before the current one.
258 $ptree->append()
260 This method appends the given text or parse-tree to the current parse-
261 tree. If the last item on the parse-tree is text and the argument is
262 also text, then the text is appended to the last item (not added as a
263 separate string). Otherwise the argument is added as a new string or
264 parse-tree after the current one.
265 $ptree->raw_text()
267 my $ptree_raw_text = $ptree->raw_text();
268 This method will return the raw text of the POD parse-tree exactly as
270 it appeared in the input.
271 Pod::ParseTree::DESTROY()
273 This method performs any necessary cleanup for the parse-tree. If you
274 override this method then it is imperative that you invoke the parent
275 method from within your own method, otherwise parse-tree storage will
276 not be reclaimed upon destruction!
277
279 See Pod::Parser, Pod::Select
280
282 Please report bugs using <http://rt.cpan.org>.
283 Brad Appleton <bradapp@enteract.com>
285
287 Hey! The above document had some coding errors, which are explained
288 below:
289 Around line 42:
291 You can't have =items (as at line 55) unless the first thing after
292 the =over is an =item
293perl v5.10.1 2009-04-12 Pod::InputObjects(3pm)