Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MDOM::Node(3)	      User Contributed Perl Documentation	 MDOM::Node(3)

NAME
       MDOM::Node - Abstract MDOM Node class, an Element that can contain
       other Elements

INHERITANCE
	 MDOM::Node
	 isa MDOM::Element

SYNOPSIS
	 # 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 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 "MDOM::Node"	objects.

METHODS
   scope
       The "scope" method returns true if the node represents a	lexical	scope
       boundary, or false if it	does not.

   add_element $Element
       The "add_element" method	adds a MDOM::Element object to the end of a
       "MDOM::Node". 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 "undef" if the
       Element was already within another Node,	or the method is not passed a
       MDOM::Element object.

   elements
       The "elements" method accesses all child	elements structurally within
       the "MDOM::Node"	object.	Note that in the base of the MDOM::Structure
       classes,	this "DOES" 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 "elements" method
       returns a count of the number of	elements.

   first_element
       The "first_element" method accesses the first element structurally
       within the "MDOM::Node" object. As for the "elements" method, this does
       include the brace tokens	for MDOM::Structure objects.

       Returns a MDOM::Element object, or "undef" if for some reason the
       "MDOM::Node" object does	not contain any	elements.

   last_element
       The "last_element" method accesses the last element structurally	within
       the "MDOM::Node"	object.	As for the "elements" method, this does
       include the brace tokens	for MDOM::Structure objects.

       Returns a MDOM::Element object, or "undef" if for some reason the
       "MDOM::Node" object does	not contain any	elements.

   children
       The "children" method accesses all child	elements lexically within the
       "MDOM::Node" object. Note that in the case of the MDOM::Structure
       classes,	this does NOT 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 "children" method
       returns a count of the number of	lexical	children.

   schildren
       The "schildren" method is really	just a convenience, the	significant-
       only variation of the normal "children" method.

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

   child $index
       The "child" method accesses a child MDOM::Element object	by its
       position	within the Node.

       Returns a MDOM::Element object, or "undef" if there is no child element
       at that node.

   schild $index
       The lexical structure of	the Perl language ignores 'insignificant'
       items, such as whitespace and comments, while MDOM 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 "schild" 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 "from the end" position.

   contains $Element
       The "contains" method is	used to	determine if another MDOM::Element
       object is logically "within" a "MDOM::Node". For	the special case of
       the brace tokens	at either side of a MDOM::Structure object, they are
       generally considered "within" 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
       "undef" on error.

   find	$class | \&wanted
       The "find" 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 "CODE"/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	"MDOM::Node"
       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 "undef" indicates no-match and no-descend.

       In the last case, the tree walker will skip over	anything below the
       "undef"-returning element and move on to	the next element at the	same
       level.

       To halt the entire search and return "undef" immediately, a condition
       function	should throw an	exception (i.e.	"die").

       Note that this same wanted logic	is used	for all	methods	documented to
       have a "\&wanted" parameter, as this one	does.

       The "find" 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 "undef" 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.

   find_first $class | \&wanted
       If the normal "find" method is like a grep, then	"find_first" is
       equivalent to the Scalar::Util "first" 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 "find" 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 "undef" if given 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, but returns true as soon as it
       finds any Elements that match the search	condition.

       See the "find" 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	"undef"	if given an invalid condition, or an error
       occurs.

   remove_child	$Element
       If passed a MDOM::Element object	that is	a direct child of the Node,
       the "remove_element" method will	remove the "Element" intact, along
       with any	of its children. As such, this method acts essentially as a
       'cut' function.

   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 is the same as for the "find"	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 "prune" method returns the number of	"Element" 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 "prune" method. It
       returns "undef" on error, which you probably should test	for.

TO DO
       - Move as much as possible to MDOM::XS

SUPPORT
       See the support section in the main module.

AUTHOR
       Adam Kennedy <adamk@cpan.org>

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.

perl v5.32.0			  2014-11-19			 MDOM::Node(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | TO DO | SUPPORT | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MDOM::Node&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help