MDOM::Node(3pm)

💖 MDOM::Node — the abstract MDOM Node class ✨

okay so bestie, welcome to MDOM::Node from the MDOM perl module docs, and honestly? she's an abstract base class and she ate. she's the Element that can contain other Elements. like, the mom friend of the tree. 🫶

---

🌈 INHERITANCE

MDOM::Node
isa MDOM::Element

so yeah, she's an MDOM::Element. girl inherited everything. 💅

---

✨ SYNOPSIS

here's the vibe check, copy-paste this energy:

# Create a typical node (a Document in this case)
my $Node = MDOM::Document->new;

# Add an element to the node( in this case, a token )
my $Token = MDOM::Token::Word->new('my');
$Node->add_element( $Token );

# Get the elements for the Node
my @elements = $Node->children;

# Find all the barewords within a Node
my $barewords = $Node->find( 'MDOM::Token::Word' );

# Find by more complex criteria
my $my_tokens = $Node->find( sub { $_[1]->content eq 'my' } );

# Remove all the whitespace
$Node->prune( 'MDOM::Token::Whitespace' );

# Remove by more complex criteria
$Node->prune( sub { $_[1]->content eq 'my' } );

---

🌸 DESCRIPTION

The MDOM::Node class is the abstract base class for all the Element classes that can hold other elements — that's MDOM::Document, MDOM::Statement, and MDOM::Structure. main character energy, fr fr. 👑

and also? every single method that works on MDOM::Element objects works on MDOM::Node objects too. no cap. ✨

---

🎀 METHODS 🎀

🦋 scope

the scope method returns true if the node is a lexical scope boundary, and false if it's not. that's it. that's the whole thing. 💅

🦋 add_element $Element

the add_element method adds an MDOM::Element object to the end of an MDOM::Node. and here's the tea: because Elements keep links back to their parent, an Element can only ever live in one Node. monogamy, but for syntax trees. 💖

Returns true if the MDOM::Element got added. Returns undef if the Element was already inside another Node, or if you didn't hand it an MDOM::Element object at all. 🙈

🦋 elements

the elements method gets you all the child elements structurally within the MDOM::Node object. heads up though: for the MDOM::Structure classes, this DOES include the brace tokens at either end of the structure. like, they're part of the fit. 🎀

Returns a list of zero or more MDOM::Element objects.

or, if you call it in scalar context, elements returns a count of how many elements there are. ✨

🦋 first_element

the first_element method grabs the first element structurally within the MDOM::Node object. same deal as elements — yes, for MDOM::Structure objects this includes the brace tokens. 💅

Returns an MDOM::Element object, or undef if for some reason the MDOM::Node object doesn't contain any elements at all. 😭

🦋 last_element

the last_element method grabs the last element structurally within the MDOM::Node object. again, same as elements — for MDOM::Structure objects this does include the brace tokens. 💅

Returns an MDOM::Element object, or undef if for some reason the MDOM::Node object has no elements. 😭

🦋 children

the children method gets you all the child elements lexically within the MDOM::Node object. and listen — for the MDOM::Structure classes, this does NOT include the brace tokens at either end of the structure. different vibe from elements, don't mix them up bestie. 🚨

Returns a list of zero of more MDOM::Element objects.

or, if you call it in scalar context, children returns a count of the number of lexical children. 🌸

🦋 schildren

the schildren method is literally just a convenience — it's the significant-only version of the regular children method. she's lowkey the same girl but filtered. ✨

In list context, returns a list of significant children. In scalar context, returns the number of significant children. 💅

🦋 child $index

the child method gets you a child MDOM::Element object by its position within the Node. 🎯

Returns an MDOM::Element object, or undef if there's no child element at that node. 😭

🦋 schild $index

okay so the lexical structure of the Perl language just ignores 'insignificant' items like whitespace and comments, but MDOM treats those as valid tokens so it can reassemble the file at any time. because of that, a lot of the time you need to find an Element inside a Node by index while only counting the lexically significant Elements. it's giving... selective vision. 🙈

the schild method returns a child Element by index, ignoring insignificant Elements. the index works exactly like a normal array — first Element is index 0, and negative indexes mean a "from the end" position. slay. 💖

🦋 contains $Element

the contains method is how you figure out if another MDOM::Element object is logically "within" an MDOM::Node. and for the special case of the brace tokens on either side of an MDOM::Structure object — they're generally considered "within" the MDOM::Structure object even if they're not actually in the elements for the MDOM::Structure. iconic little loophole. 🎀

Returns true if the MDOM::Element is within us, false if not, or undef on error. 💅

🦋 find $class | &wanted

the find method searches inside a code tree for MDOM::Element objects that meet a particular condition. 🔍

to specify the condition, you can give the method either a simple class name (full or shortened), or a CODE/function reference. chef's kiss, both work.

# Find all single quotes in a Document (which is a Node)
$Document->find('MDOM::Quote::Single');

# The same thing with a shortened class name
$Document->find('Quote::Single');

# Anything more elaborate, we so with the sub
$Document->find( sub {
      # At the top level of the file...
      $_[1]->parent == $_[0]
      and (
              # ...find all comments and POD
              $_[1]->isa('MDOM::Token::Pod')
              or
              $_[1]->isa('MDOM::Token::Comment')
      )
} );

the function gets passed two arguments: the top-level MDOM::Node you're searching in, and the current MDOM::Element that the condition is testing. 🫶

the anonymous function should return one of three values:

1. returning true means the condition matched ✨
2. defined-false (0 or '') means no-match 🙅
3. undef means no-match AND no-descend 🚫

in that last case, the tree walker skips over everything below the undef-returning element and moves on to the next element at the same level. bye girl. 👋

to halt the entire search and return undef immediately, a condition function should throw an exception (i.e. die). dramatic but valid. 💀

heads up: this exact same wanted logic is used for all methods documented to have a \&wanted parameter, and this one does. so learn it once, use it everywhere. iykyk. 💅

the find method returns a reference to an array of MDOM::Element objects that match the condition, false (but defined!) if no Elements match, or undef if you gave a bad condition, or if an error happens during the search. 😭

and if your condition was bad, a warning gets emitted too. so like, read it. 🙈

🦋 find_first $class | &wanted

if the normal find method is like a grep, then find_first is basically the Scalar::Util first function. same energy, less output. ✨

give it an element class or a wanted function, and it searches depth-first through the tree until it finds something matching the condition, returning the first Element it runs into. 🎯

see the find method for the details on the format of the search condition.

Returns the first MDOM::Element object that matches the condition, false if nothing matches, or undef if you gave an invalid condition, or an error occurs. 💖

🦋 find_any $class | &wanted

the find_any method is a short-circuiting true/false method that behaves like the normal find method, except it returns true the second it finds <em>any</em> Elements matching the search condition. she does not wait around. 💅

see the find method for the details on the format of the search condition.

Returns true if any Elements matching the condition can be found, false if not, or undef if you gave an invalid condition, or an error occurs. 🌸

🦋 remove_child $Element

if you pass it an MDOM::Element object that's a direct child of the Node, the remove_element method removes the Element intact, along with all of its children. so basically this method is acting as a 'cut' function. snip snip bestie. ✂️

🦋 source

Returns the makefile source for the current node. 📄

🦋 prune $class | &wanted

the prune method is used to strip MDOM::Element objects out of a code tree. the argument works the same as for the find method — either a class name, or an anonymous subroutine that returns true/false. any Element matching the class|wanted gets deleted from the code tree, along with all of its children. it's giving spring cleaning. 🧹

the prune method returns the number of Element objects that matched and were removed, non-recursively. and this number might also be zero, so please do not do a simple true/false test on the return value of prune. it returns undef on error, which you probably <em>should</em> test for. 💀

fr fr, this is the classic trap. 0 removed is a perfectly fine, happy result. don't @ me, just check for undef. 🫶

---

🧚 TO DO

• Move as much as possible to MDOM::XS

---

🌈 SUPPORT

See the support section in the main module. (go look, it's right there 💖)

---

👑 AUTHOR

Adam Kennedy <adamk@cpan.org> — legend behaviour. 💜

---

🍓 COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

and that's the whole page bestie!! this one's from the perl v5.34.0 docs, dated 2022-06-15, and she's MDOM::Node(3pm) — User Contributed Perl Documentation. now go build a tree, you got this. 💖✨🎀