1MDOM::Node(3)         User Contributed Perl Documentation        MDOM::Node(3)
2
3
4

NAME

6       MDOM::Node - Abstract MDOM Node class, an Element that can contain
7       other Elements
8

INHERITANCE

10         MDOM::Node
11         isa MDOM::Element
12

SYNOPSIS

14         # Create a typical node (a Document in this case)
15         my $Node = MDOM::Document->new;
16
17         # Add an element to the node( in this case, a token )
18         my $Token = MDOM::Token::Word->new('my');
19         $Node->add_element( $Token );
20
21         # Get the elements for the Node
22         my @elements = $Node->children;
23
24         # Find all the barewords within a Node
25         my $barewords = $Node->find( 'MDOM::Token::Word' );
26
27         # Find by more complex criteria
28         my $my_tokens = $Node->find( sub { $_[1]->content eq 'my' } );
29
30         # Remove all the whitespace
31         $Node->prune( 'MDOM::Token::Whitespace' );
32
33         # Remove by more complex criteria
34         $Node->prune( sub { $_[1]->content eq 'my' } );
35

DESCRIPTION

37       The "MDOM::Node" class provides an abstract base class for the Element
38       classes that are able to contain other elements MDOM::Document,
39       MDOM::Statement, and MDOM::Structure.
40
41       As well as those listed below, all of the methods that apply to
42       MDOM::Element objects also apply to "MDOM::Node" objects.
43

METHODS

45   scope
46       The "scope" method returns true if the node represents a lexical scope
47       boundary, or false if it does not.
48
49   add_element $Element
50       The "add_element" method adds a MDOM::Element object to the end of a
51       "MDOM::Node". Because Elements maintain links to their parent, an
52       Element can only be added to a single Node.
53
54       Returns true if the MDOM::Element was added. Returns "undef" if the
55       Element was already within another Node, or the method is not passed a
56       MDOM::Element object.
57
58   elements
59       The "elements" method accesses all child elements structurally within
60       the "MDOM::Node" object. Note that in the base of the MDOM::Structure
61       classes, this "DOES" include the brace tokens at either end of the
62       structure.
63
64       Returns a list of zero or more MDOM::Element objects.
65
66       Alternatively, if called in the scalar context, the "elements" method
67       returns a count of the number of elements.
68
69   first_element
70       The "first_element" method accesses the first element structurally
71       within the "MDOM::Node" object. As for the "elements" method, this does
72       include the brace tokens for MDOM::Structure objects.
73
74       Returns a MDOM::Element object, or "undef" if for some reason the
75       "MDOM::Node" object does not contain any elements.
76
77   last_element
78       The "last_element" method accesses the last element structurally within
79       the "MDOM::Node" object. As for the "elements" method, this does
80       include the brace tokens for MDOM::Structure objects.
81
82       Returns a MDOM::Element object, or "undef" if for some reason the
83       "MDOM::Node" object does not contain any elements.
84
85   children
86       The "children" method accesses all child elements lexically within the
87       "MDOM::Node" object. Note that in the case of the MDOM::Structure
88       classes, this does NOT include the brace tokens at either end of the
89       structure.
90
91       Returns a list of zero of more MDOM::Element objects.
92
93       Alternatively, if called in the scalar context, the "children" method
94       returns a count of the number of lexical children.
95
96   schildren
97       The "schildren" method is really just a convenience, the significant-
98       only variation of the normal "children" method.
99
100       In list context, returns a list of significant children. In scalar
101       context, returns the number of significant children.
102
103   child $index
104       The "child" method accesses a child MDOM::Element object by its
105       position within the Node.
106
107       Returns a MDOM::Element object, or "undef" if there is no child element
108       at that node.
109
110   schild $index
111       The lexical structure of the Perl language ignores 'insignificant'
112       items, such as whitespace and comments, while MDOM treats these items
113       as valid tokens so that it can reassemble the file at any time. Because
114       of this, in many situations there is a need to find an Element within a
115       Node by index, only counting lexically significant Elements.
116
117       The "schild" method returns a child Element by index, ignoring
118       insignificant Elements. The index of a child Element is specified in
119       the same way as for a normal array, with the first Element at index 0,
120       and negative indexes used to identify a "from the end" position.
121
122   contains $Element
123       The "contains" method is used to determine if another MDOM::Element
124       object is logically "within" a "MDOM::Node". For the special case of
125       the brace tokens at either side of a MDOM::Structure object, they are
126       generally considered "within" a MDOM::Structure object, even if they
127       are not actually in the elements for the MDOM::Structure.
128
129       Returns true if the MDOM::Element is within us, false if not, or
130       "undef" on error.
131
132   find $class | \&wanted
133       The "find" method is used to search within a code tree for
134       MDOM::Element objects that meet a particular condition.
135
136       To specify the condition, the method can be provided with either a
137       simple class name (full or shortened), or a "CODE"/function reference.
138
139         # Find all single quotes in a Document (which is a Node)
140         $Document->find('MDOM::Quote::Single');
141
142         # The same thing with a shortened class name
143         $Document->find('Quote::Single');
144
145         # Anything more elaborate, we so with the sub
146         $Document->find( sub {
147               # At the top level of the file...
148               $_[1]->parent == $_[0]
149               and (
150                       # ...find all comments and POD
151                       $_[1]->isa('MDOM::Token::Pod')
152                       or
153                       $_[1]->isa('MDOM::Token::Comment')
154               )
155         } );
156
157       The function will be passed two arguments, the top-level "MDOM::Node"
158       you are searching in and the current MDOM::Element that the condition
159       is testing.
160
161       The anonymous function should return one of three values. Returning
162       true indicates a condition match, defined-false (0 or '') indicates no-
163       match, and "undef" indicates no-match and no-descend.
164
165       In the last case, the tree walker will skip over anything below the
166       "undef"-returning element and move on to the next element at the same
167       level.
168
169       To halt the entire search and return "undef" immediately, a condition
170       function should throw an exception (i.e. "die").
171
172       Note that this same wanted logic is used for all methods documented to
173       have a "\&wanted" parameter, as this one does.
174
175       The "find" method returns a reference to an array of MDOM::Element
176       objects that match the condition, false (but defined) if no Elements
177       match the condition, or "undef" if you provide a bad condition, or an
178       error occurs during the search process.
179
180       In the case of a bad condition, a warning will be emitted as well.
181
182   find_first $class | \&wanted
183       If the normal "find" method is like a grep, then "find_first" is
184       equivalent to the Scalar::Util "first" function.
185
186       Given an element class or a wanted function, it will search depth-first
187       through a tree until it finds something that matches the condition,
188       returning the first Element that it encounters.
189
190       See the "find" method for details on the format of the search
191       condition.
192
193       Returns the first MDOM::Element object that matches the condition,
194       false if nothing matches the condition, or "undef" if given an invalid
195       condition, or an error occurs.
196
197   find_any $class | \&wanted
198       The "find_any" method is a short-circuiting true/false method that
199       behaves like the normal "find" method, but returns true as soon as it
200       finds any Elements that match the search condition.
201
202       See the "find" method for details on the format of the search
203       condition.
204
205       Returns true if any Elements that match the condition can be found,
206       false if not, or "undef" if given an invalid condition, or an error
207       occurs.
208
209   remove_child $Element
210       If passed a MDOM::Element object that is a direct child of the Node,
211       the "remove_element" method will remove the "Element" intact, along
212       with any of its children. As such, this method acts essentially as a
213       'cut' function.
214
215   source
216       Returns the makefile source for the current node
217
218   prune $class | \&wanted
219       The "prune" method is used to strip MDOM::Element objects out of a code
220       tree. The argument is the same as for the "find" method, either a class
221       name, or an anonymous subroutine which returns true/false. Any Element
222       that matches the class|wanted will be deleted from the code tree, along
223       with any of its children.
224
225       The "prune" method returns the number of "Element" objects that matched
226       and were removed, non-recursively. This might also be zero, so avoid a
227       simple true/false test on the return false of the "prune" method. It
228       returns "undef" on error, which you probably should test for.
229

TO DO

231       - Move as much as possible to MDOM::XS
232

SUPPORT

234       See the support section in the main module.
235

AUTHOR

237       Adam Kennedy <adamk@cpan.org>
238
240       Copyright 2001 - 2006 Adam Kennedy.
241
242       This program is free software; you can redistribute it and/or modify it
243       under the same terms as Perl itself.
244
245       The full text of the license can be found in the LICENSE file included
246       with this module.
247
248
249
250perl v5.38.0                      2023-07-20                     MDOM::Node(3)
Impressum