1Pod::Abstract::Node(3)User Contributed Perl DocumentationPod::Abstract::Node(3)
2
3
4

NAME

6       Pod::Abstract::Node - Pod Document Node.
7

SYNOPSIS

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

METHODS

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

AUTHOR

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)
Impressum