1Pod::InputObjects(3) User Contributed Perl Documentation Pod::InputObjects(3)
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 NOTE: This module is considered legacy; modern Perl releases (5.31.1
20 and higher) are going to remove Pod-Parser from core and use
21 Pod::Simple for all things POD.
22 This module defines some basic input objects used by Pod::Parser when
24 reading and parsing POD text from an input source. The following
25 objects are defined:
26 package Pod::Paragraph
28 An object corresponding to a paragraph of POD input text. It may be
29 a plain paragraph, a verbatim paragraph, or a command paragraph
30 (see perlpod).
31 package Pod::InteriorSequence
33 An object corresponding to an interior sequence command from the
34 POD input text (see perlpod).
35 package Pod::ParseTree
37 An object corresponding to a tree of parsed POD text. Each "node"
38 in a parse-tree (or ptree) is either a text-string or a reference
39 to a Pod::InteriorSequence object. The nodes appear in the parse-
40 tree in the order in which they were parsed from left-to-right.
41 Each of these input objects are described in further detail in the
43 sections which follow.
44
46 An object representing a paragraph of POD input text. It has the
47 following methods/attributes:
48 Pod::Paragraph->new()
50 my $pod_para1 = Pod::Paragraph->new(-text => $text);
51 my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
52 -text => $text);
53 my $pod_para3 = new Pod::Paragraph(-text => $text);
54 my $pod_para4 = new Pod::Paragraph(-name => $cmd,
55 -text => $text);
56 my $pod_para5 = Pod::Paragraph->new(-name => $cmd,
57 -text => $text,
58 -file => $filename,
59 -line => $line_number);
60 This is a class method that constructs a "Pod::Paragraph" object and
62 returns a reference to the new paragraph object. It may be given one or
63 two keyword arguments. The "-text" keyword indicates the corresponding
64 text of the POD paragraph. The "-name" keyword indicates the name of
65 the corresponding POD command, such as "head1" or "item" (it should not
66 contain the "=" prefix); this is needed only if the POD paragraph
67 corresponds to a command paragraph. The "-file" and "-line" keywords
68 indicate the filename and line number corresponding to the beginning of
69 the paragraph
70 $pod_para->cmd_name()
72 my $para_cmd = $pod_para->cmd_name();
73 If this paragraph is a command paragraph, then this method will return
75 the name of the command (without any leading "=" prefix).
76 $pod_para->text()
78 my $para_text = $pod_para->text();
79 This method will return the corresponding text of the paragraph.
81 $pod_para->raw_text()
83 my $raw_pod_para = $pod_para->raw_text();
84 This method will return the raw text of the POD paragraph, exactly as
86 it appeared in the input.
87 $pod_para->cmd_prefix()
89 my $prefix = $pod_para->cmd_prefix();
90 If this paragraph is a command paragraph, then this method will return
92 the prefix used to denote the command (which should be the string "="
93 or "==").
94 $pod_para->cmd_separator()
96 my $separator = $pod_para->cmd_separator();
97 If this paragraph is a command paragraph, then this method will return
99 the text used to separate the command name from the rest of the
100 paragraph (if any).
101 $pod_para->parse_tree()
103 my $ptree = $pod_parser->parse_text( $pod_para->text() );
104 $pod_para->parse_tree( $ptree );
105 $ptree = $pod_para->parse_tree();
106 This method will get/set the corresponding parse-tree of the
108 paragraph's text.
109 $pod_para->file_line()
111 my ($filename, $line_number) = $pod_para->file_line();
112 my $position = $pod_para->file_line();
113 Returns the current filename and line number for the paragraph object.
115 If called in a list context, it returns a list of two elements: first
116 the filename, then the line number. If called in a scalar context, it
117 returns a string containing the filename, followed by a colon (':'),
118 followed by the line number.
119
121 An object representing a POD interior sequence command. It has the
122 following methods/attributes:
123 Pod::InteriorSequence->new()
125 my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
126 -ldelim => $delimiter);
127 my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd,
128 -ldelim => $delimiter);
129 my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd,
130 -ldelim => $delimiter,
131 -file => $filename,
132 -line => $line_number);
133 my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree);
135 my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree);
136 This is a class method that constructs a "Pod::InteriorSequence" object
138 and returns a reference to the new interior sequence object. It should
139 be given two keyword arguments. The "-ldelim" keyword indicates the
140 corresponding left-delimiter of the interior sequence (e.g. '<'). The
141 "-name" keyword indicates the name of the corresponding interior
142 sequence command, such as "I" or "B" or "C". The "-file" and "-line"
143 keywords indicate the filename and line number corresponding to the
144 beginning of the interior sequence. If the $ptree argument is given, it
145 must be the last argument, and it must be either string, or else an
146 array-ref suitable for passing to Pod::ParseTree::new (or it may be a
147 reference to a Pod::ParseTree object).
148 $pod_seq->cmd_name()
150 my $seq_cmd = $pod_seq->cmd_name();
151 The name of the interior sequence command.
153 $pod_seq->prepend()
155 $pod_seq->prepend($text);
156 $pod_seq1->prepend($pod_seq2);
157 Prepends the given string or parse-tree or sequence object to the
159 parse-tree of this interior sequence.
160 $pod_seq->append()
162 $pod_seq->append($text);
163 $pod_seq1->append($pod_seq2);
164 Appends the given string or parse-tree or sequence object to the parse-
166 tree of this interior sequence.
167 $pod_seq->nested()
169 $outer_seq = $pod_seq->nested || print "not nested";
170 If this interior sequence is nested inside of another interior
172 sequence, then the outer/parent sequence that contains it is returned.
173 Otherwise "undef" is returned.
174 $pod_seq->raw_text()
176 my $seq_raw_text = $pod_seq->raw_text();
177 This method will return the raw text of the POD interior sequence,
179 exactly as it appeared in the input.
180 $pod_seq->left_delimiter()
182 my $ldelim = $pod_seq->left_delimiter();
183 The leftmost delimiter beginning the argument text to the interior
185 sequence (should be "<").
186 $pod_seq->right_delimiter()
188 The rightmost delimiter beginning the argument text to the interior
189 sequence (should be ">").
190 $pod_seq->parse_tree()
192 my $ptree = $pod_parser->parse_text($paragraph_text);
193 $pod_seq->parse_tree( $ptree );
194 $ptree = $pod_seq->parse_tree();
195 This method will get/set the corresponding parse-tree of the interior
197 sequence's text.
198 $pod_seq->file_line()
200 my ($filename, $line_number) = $pod_seq->file_line();
201 my $position = $pod_seq->file_line();
202 Returns the current filename and line number for the interior sequence
204 object. If called in a list context, it returns a list of two
205 elements: first the filename, then the line number. If called in a
206 scalar context, it returns a string containing the filename, followed
207 by a colon (':'), followed by the line number.
208 Pod::InteriorSequence::DESTROY()
210 This method performs any necessary cleanup for the interior-sequence.
211 If you override this method then it is imperative that you invoke the
212 parent method from within your own method, otherwise interior-sequence
213 storage will not be reclaimed upon destruction!
214
216 This object corresponds to a tree of parsed POD text. As POD text is
217 scanned from left to right, it is parsed into an ordered list of text-
218 strings and Pod::InteriorSequence objects (in order of appearance). A
219 Pod::ParseTree object corresponds to this list of strings and
220 sequences. Each interior sequence in the parse-tree may itself contain
221 a parse-tree (since interior sequences may be nested).
222 Pod::ParseTree->new()
224 my $ptree1 = Pod::ParseTree->new;
225 my $ptree2 = new Pod::ParseTree;
226 my $ptree4 = Pod::ParseTree->new($array_ref);
227 my $ptree3 = new Pod::ParseTree($array_ref);
228 This is a class method that constructs a "Pod::Parse_tree" object and
230 returns a reference to the new parse-tree. If a single-argument is
231 given, it must be a reference to an array, and is used to initialize
232 the root (top) of the parse tree.
233 $ptree->top()
235 my $top_node = $ptree->top();
236 $ptree->top( $top_node );
237 $ptree->top( @children );
238 This method gets/sets the top node of the parse-tree. If no arguments
240 are given, it returns the topmost node in the tree (the root), which is
241 also a Pod::ParseTree. If it is given a single argument that is a
242 reference, then the reference is assumed to a parse-tree and becomes
243 the new top node. Otherwise, if arguments are given, they are treated
244 as the new list of children for the top node.
245 $ptree->children()
247 This method gets/sets the children of the top node in the parse-tree.
248 If no arguments are given, it returns the list (array) of children
249 (each of which should be either a string or a Pod::InteriorSequence.
250 Otherwise, if arguments are given, they are treated as the new list of
251 children for the top node.
252 $ptree->prepend()
254 This method prepends the given text or parse-tree to the current parse-
255 tree. If the first item on the parse-tree is text and the argument is
256 also text, then the text is prepended to the first item (not added as a
257 separate string). Otherwise the argument is added as a new string or
258 parse-tree before the current one.
259 $ptree->append()
261 This method appends the given text or parse-tree to the current parse-
262 tree. If the last item on the parse-tree is text and the argument is
263 also text, then the text is appended to the last item (not added as a
264 separate string). Otherwise the argument is added as a new string or
265 parse-tree after the current one.
266 $ptree->raw_text()
268 my $ptree_raw_text = $ptree->raw_text();
269 This method will return the raw text of the POD parse-tree exactly as
271 it appeared in the input.
272 Pod::ParseTree::DESTROY()
274 This method performs any necessary cleanup for the parse-tree. If you
275 override this method then it is imperative that you invoke the parent
276 method from within your own method, otherwise parse-tree storage will
277 not be reclaimed upon destruction!
278
280 Pod::InputObjects is part of the Pod::Parser distribution.
281 See Pod::Parser, Pod::Select
283
285 Please report bugs using <http://rt.cpan.org>.
286 Brad Appleton <bradapp@enteract.com>
288perl v5.38.0 2023-07-21 Pod::InputObjects(3)