Abstract mdom node class, an element that can contain other elements
MDOM::Node isa MDOM::Element
# 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' } );
The \*(C`MDOM::Node\*(C' class provides an abstract base class for the Element classes that are able to contain other elements MDOM::Document, MDOM::Statement, and MDOM::Structure.
As well as those listed below, all of the methods that apply to MDOM::Element objects also apply to \*(C`MDOM::Node\*(C' objects.
The \*(C`scope\*(C' method returns true if the node represents a lexical scope boundary, or false if it does not. The \*(C`add_element\*(C' method adds a MDOM::Element object to the end of a \*(C`MDOM::Node\*(C'. Because Elements maintain links to their parent, an Element can only be added to a single Node.
Returns true if the MDOM::Element was added. Returns \*(C`undef\*(C' if the Element was already within another Node, or the method is not passed a MDOM::Element object.
The \*(C`elements\*(C' method accesses all child elements structurally within the \*(C`MDOM::Node\*(C' object. Note that in the base of the MDOM::Structure classes, this \*(C`DOES\*(C' include the brace tokens at either end of the structure.
Returns a list of zero or more MDOM::Element objects.
Alternatively, if called in the scalar context, the \*(C`elements\*(C' method returns a count of the number of elements.
The \*(C`first_element\*(C' method accesses the first element structurally within the \*(C`MDOM::Node\*(C' object. As for the \*(C`elements\*(C' method, this does include the brace tokens for MDOM::Structure objects.
Returns a MDOM::Element object, or \*(C`undef\*(C' if for some reason the \*(C`MDOM::Node\*(C' object does not contain any elements.
The \*(C`last_element\*(C' method accesses the last element structurally within the \*(C`MDOM::Node\*(C' object. As for the \*(C`elements\*(C' method, this does include the brace tokens for MDOM::Structure objects.
Returns a MDOM::Element object, or \*(C`undef\*(C' if for some reason the \*(C`MDOM::Node\*(C' object does not contain any elements.
The \*(C`children\*(C' method accesses all child elements lexically within the \*(C`MDOM::Node\*(C' object. Note that in the case of the MDOM::Structure classes, this does \s-1NOT\s0 include the brace tokens at either end of the structure.
Returns a list of zero of more MDOM::Element objects.
Alternatively, if called in the scalar context, the \*(C`children\*(C' method returns a count of the number of lexical children.
The \*(C`schildren\*(C' method is really just a convenience, the significant-only variation of the normal \*(C`children\*(C' method.
In list context, returns a list of significant children. In scalar context, returns the number of significant children. The \*(C`child\*(C' method accesses a child MDOM::Element object by its position within the Node.
Returns a MDOM::Element object, or \*(C`undef\*(C' if there is no child element at that node. The lexical structure of the Perl language ignores 'insignificant' items, such as whitespace and comments, while \s-1MDOM\s0 treats these items as valid tokens so that it can reassemble the file at any time. Because of this, in many situations there is a need to find an Element within a Node by index, only counting lexically significant Elements.
The \*(C`schild\*(C' method returns a child Element by index, ignoring insignificant Elements. The index of a child Element is specified in the same way as for a normal array, with the first Element at index 0, and negative indexes used to identify a \*(L"from the end\*(R" position. The \*(C`contains\*(C' method is used to determine if another MDOM::Element object is logically \*(L"within\*(R" a \*(C`MDOM::Node\*(C'. For the special case of the brace tokens at either side of a MDOM::Structure object, they are generally considered \*(L"within\*(R" a MDOM::Structure object, even if they are not actually in the elements for the MDOM::Structure.
Returns true if the MDOM::Element is within us, false if not, or \*(C`undef\*(C' on error. The \*(C`find\*(C' method is used to search within a code tree for MDOM::Element objects that meet a particular condition.
To specify the condition, the method can be provided with either a simple class name (full or shortened), or a \*(C`CODE\*(C'/function reference.
# 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 will be passed two arguments, the top-level \*(C`MDOM::Node\*(C' you are searching in and the current MDOM::Element that the condition is testing.
The anonymous function should return one of three values. Returning true indicates a condition match, defined-false (0 or '') indicates no-match, and \*(C`undef\*(C' indicates no-match and no-descend.
In the last case, the tree walker will skip over anything below the \*(C`undef\*(C'-returning element and move on to the next element at the same level.
To halt the entire search and return \*(C`undef\*(C' immediately, a condition function should throw an exception (i.e. \*(C`die\*(C').
Note that this same wanted logic is used for all methods documented to have a \*(C`\&wanted\*(C' parameter, as this one does.
The \*(C`find\*(C' method returns a reference to an array of MDOM::Element objects that match the condition, false (but defined) if no Elements match the condition, or \*(C`undef\*(C' if you provide a bad condition, or an error occurs during the search process.
In the case of a bad condition, a warning will be emitted as well. If the normal \*(C`find\*(C' method is like a grep, then \*(C`find_first\*(C' is equivalent to the Scalar::Util \*(C`first\*(C' function.
Given an element class or a wanted function, it will search depth-first through a tree until it finds something that matches the condition, returning the first Element that it encounters.
See the \*(C`find\*(C' method for details on the format of the search condition.
Returns the first MDOM::Element object that matches the condition, false if nothing matches the condition, or \*(C`undef\*(C' if given an invalid condition, or an error occurs. The \*(C`find_any\*(C' method is a short-circuiting true/false method that behaves like the normal \*(C`find\*(C' method, but returns true as soon as it finds any Elements that match the search condition.
See the \*(C`find\*(C' method for details on the format of the search condition.
Returns true if any Elements that match the condition can be found, false if not, or \*(C`undef\*(C' if given an invalid condition, or an error occurs. If passed a MDOM::Element object that is a direct child of the Node, the \*(C`remove_element\*(C' method will remove the \*(C`Element\*(C' intact, along with any of its children. As such, this method acts essentially as a 'cut' function.
Returns the makefile source for the current node The \*(C`prune\*(C' method is used to strip MDOM::Element objects out of a code tree. The argument is the same as for the \*(C`find\*(C' method, either a class name, or an anonymous subroutine which returns true/false. Any Element that matches the class|wanted will be deleted from the code tree, along with any of its children.
The \*(C`prune\*(C' method returns the number of \*(C`Element\*(C' objects that matched and were removed, non-recursively. This might also be zero, so avoid a simple true/false test on the return false of the \*(C`prune\*(C' method. It returns \*(C`undef\*(C' on error, which you probably should test for.
- Move as much as possible to \s-1MDOM::XS\s0
See the support section in the main module.
Adam Kennedy <[email protected]>
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 \s-1LICENSE\s0 file included with this module.