1Pod::Abstract::Node(3)User Contributed Perl DocumentationPod::Abstract::Node(3)
2
3
4
6 Pod::Abstract::Node - Pod Document Node.
7
9 $node->nest( @list ); # Nests list as children of $node. If they
10 # exist in a tree they will be detached.
11 $node->clear; # Remove (detach) all children of $node
12 $node->hoist; # Append all children of $node after $node.
13 $node->detach; # Detaches intact subtree from parent
14 $node->select( $path_exp ); # Selects the path expression under $node
15 $node->select_into( $target, $path_exp );
16 # Selects into the children of the
17 # target node. (copies)
18
19 $node->insert_before($target); # Inserts $node in $target's tree
20 # before $target
21 $node->insert_after($target);
22
23 $node->push($target); # Appends $target at the end of this node
24 $node->unshift($target); # Prepends $target at the start of this node
25
26 $node->path(); # List of nodes leading to this one
27 $node->children(); # All direct child nodes of this one
28 $node->next(); # Following sibling if present
29 $node->previous(); # Preceding sibling if present
30
31 $node->duplicate(); # Duplicate node and children in a new tree.
32
33 $node->pod; # Convert node back into literal POD
34 $node->ptree; # Show visual (abbreviated) parse tree
35
37 new
38 my $node = Pod::Abstract::Node->new(
39 type => ':text', body => 'Some text',
40 );
41
42 Creates a new, unattached Node object. This is NOT the recommended way
43 to make nodes to add to a document, use Pod::Abstract::BuildNode for
44 that. There are specific rules about how data must be set up for these
45 nodes, and "new" lets you ignore them.
46
47 Apart from type and body, all other hash arguments will be converted
48 into "params", which may be internal data or node attributes.
49
50 Type may be:
51
52 • A plain word, which is taken to be a command name.
53
54 • ":paragraph", ":text", ":verbatim" or <:X> (where X is an inline
55 format letter). These will be treated as you would expect.
56
57 • "#cut", meaning this is literal, non-pod text.
58
59 Note that these do not guarantee the resulting document structure will
60 match your types - types are derived from the document, not the other
61 way around. If your types do not match your document they will mutate
62 when it is reloaded.
63
64 See Pod::Abstract::BuildNode if you want to make nodes easily for
65 creating/modifying a document tree.
66
67 ptree
68 print $n->ptree;
69
70 Produces a formatted, readable, parse tree. Shows node types, nesting
71 structure, abbreviated text. Does NOT show all information, but shows
72 enough to help debug parsing/traversal problems.
73
74 text
75 print $n->text;
76
77 Returns the text subnodes only of the given node, concatenated together
78 - i,e, the text only with no formatting at all.
79
80 pod
81 print $n->pod;
82
83 Returns the node (and all subnodes) formatted as POD. A newly loaded
84 node should produce the original POD text when pod is requested.
85
86 select
87 my @nodes = $n->select('/:paragraph[//:text =~ {TODO}]');
88
89 Select a pPath expression against this node. The above example will
90 select all paragraphs in the document containing 'TODO' in any of their
91 text nodes.
92
93 The returned values are the real nodes from the document tree, and
94 manipulating them will transform the document.
95
96 select_into
97 $node->select_into($target_node, $path)
98
99 As with select, this will match a pPath expression against $node - but
100 the resulting nodes will be copied and added as children to
101 $target_node. The nodes that were added will be returned as a list.
102
103 type
104 $node->type( [ $new_type ] );
105
106 Get or set the type of the node.
107
108 body
109 $node->body( [ $new_body ] );
110
111 Get or set the node body text. This is NOT the child tree of the node,
112 it is the literal text as used by text/verbatim nodes.
113
114 param
115 $node->param( $p_name [, $p_value ] );
116
117 Get or set the named parameter. Any value can be used, but for document
118 attributes a Pod::Abstract::Node should be set.
119
120 duplicate
121 my $new_node = $node->duplicate;
122
123 Make a deep-copy of the node. The duplicate node returned has an
124 identical document tree, but different node identifiers.
125
126 insert_before
127 $node->insert_before($target);
128
129 Inserts $node before $target, as a sibling of $target. If $node is
130 already in a document tree, it will be removed from it's existing
131 position.
132
133 insert_after
134 $node->insert_after($target);
135
136 Inserts $node after $target, as a sibling of $target. If $node is
137 already in a document tree, it will be removed from it's existing
138 position.
139
140 hoist
141 $node->hoist;
142
143 Inserts all children of $node, in order, immediately after $node. After
144 this operation, $node will have no children. In pictures:
145
146 - a
147 - b
148 - c
149 - d
150 -f
151
152 $a->hoist; # ->
153
154 - a
155 - b
156 - c
157 - d
158 - f
159
160 clear
161 $node->clear;
162
163 Detach all children of $node. The detached nodes will be returned, and
164 can be safely reused, but they will no longer be in the document tree.
165
166 push
167 $node->push($target);
168
169 Pushes $target at the end of $node's children.
170
171 nest
172 $node->nest(@new_children);
173
174 Adds @new_children to $node's children. The new nodes will be added at
175 the end of any existing children. This can be considered the inverse of
176 hoist.
177
178 unshift
179 $node->unshift($target);
180
181 The reverse of push, add a node to the start of $node's children.
182
183 serial
184 $node->serial;
185
186 The unique serial number of $node. This should never be modified.
187
188 attached
189 $node->attached;
190
191 Returns true if $node is attached to a document tree.
192
193 detach
194 $node->detach;
195
196 Removes a node from it's document tree. Returns true if the node was
197 removed from a tree, false otherwise. After this operation, the node
198 will be detached.
199
200 Detached nodes can be reused safely.
201
202 parent
203 $node->parent;
204
205 Returns the parent of $node if available. Returns undef if no parent.
206
207 root
208 $node->root
209
210 Find the root node for the tree holding this node - this may be the
211 original node if it has no parent.
212
213 children
214 my @children = $node->children;
215
216 Returns the children of the node in document order.
217
218 next
219 my $next = $node->next;
220
221 Returns the following sibling of $node, if one exists. If there is no
222 following node undef will be returned.
223
224 previous
225 my $previous = $node->previous;
226
227 Returns the preceding sibling of $node, if one exists. If there is no
228 preceding node, undef will be returned.
229
230 coalesce_body
231 $node->coalesce_body(':verbatim');
232
233 This performs node coalescing as required by perlpodspec. Successive
234 verbatim nodes can be merged into a single node. This is also done with
235 text nodes, primarily for =begin/=end blocks.
236
237 The named node type will be merged together in the child document
238 wherever there are two or more successive nodes of that type. Don't use
239 for anything except ":text" and ":verbatim" nodes unless you're really
240 sure you know what you want.
241
243 Ben Lilburne <bnej@mac.com>
244
246 Copyright (C) 2009 Ben Lilburne
247
248 This program is free software; you can redistribute it and/or modify it
249 under the same terms as Perl itself.
250
251
252
253perl v5.34.0 2021-07-22 Pod::Abstract::Node(3)