File Coverage

blib/lib/XML/Mini/Element.pm

Criterion	Covered	Total	%
statement	305	432	70.6
branch	97	194	50.0
condition	27	49	55.1
subroutine	32	40	80.0
pod	26	31	83.8
total	487	746	65.2

package XML::Mini::Element;
use strict;
$^W = 1;

use XML::Mini;
use XML::Mini::TreeComponent;
use XML::Mini::Element::Comment;
use XML::Mini::Element::DocType;
use XML::Mini::Element::Entity;
use XML::Mini::Element::CData;

use vars qw ( $VERSION @ISA );
push @ISA, qw ( XML::Mini::TreeComponent );
$VERSION = '1.38';

sub new
{
    my $class = shift;
    my $name = shift;

    my $self = {};
    bless $self, ref $class || $class;

    $self->{'_attributes'} = {};
    $self->{'_numChildren'} = 0;
    $self->{'_numElementChildren'} = 0;
    $self->{'_children'} = [];
    $self->{'_avoidLoops'} = $XML::Mini::AvoidLoops;

    if ($name)
    {
	$self->name($name);
    } else {
	return XML::Mini->Error("Must pass a name to create a new Element.");
    }

    return $self;
}

sub name
{
    my $self = shift;
    my $name = shift;

    if (defined $name)
    {
	$self->{'_name'} = $name;
    }

    return $self->{'_name'};
}

sub attribute
{
    my $self = shift;
    my $name = shift || return undef;
    my $primValue = shift;
    my $altValue = shift;

    my $value = (defined $primValue) ? $primValue : $altValue;

    if (defined $value)
    {
	$self->{'_attributes'}->{$name} = $value;
    } else {
    	$self->{'_attributes'}->{$name} = ''
		unless (defined $self->{'_attributes'}->{$name});
    }

    if (defined $self->{'_attributes'}->{$name})
    {
	return $self->{'_attributes'}->{$name};
    }

    return undef;
}

sub text
{
    my $self = shift;
    my $primValue = shift;
    my $altValue = shift;

    my $setTo = (defined $primValue) ? $primValue : $altValue;

    if (defined $setTo)
    {
	$self->createNode($setTo);
    }

    my @contents;

    foreach my $child (@{$self->{'_children'}})
    {
	my $value = $child->getValue();
	if (defined $value)
	{
	    push @contents, $value;
	}
    }

    if (scalar @contents)
    {
	my $retStr = join(' ', @contents);
	return $retStr;
    }

    return undef;
}

sub numeric
{
    my $self = shift;
    my $primValue = shift;
    my $altValue = shift;

    my $setTo = (defined $primValue) ? $primValue : $altValue;

    if (defined $setTo)
    {
	return XML::Mini->Error("Must pass a NUMERIC value to Element::numeric() to set ($setTo)")
	    unless ($setTo =~ m/^\s*[Ee\d\.\+-]+\s*$/);

	$self->text($setTo);
    }


    my @contents;
    foreach my $child (@{$self->{'_children'}})
    {
	my $value = $child->getValue();
	if (defined $value)
	{
	    push @contents, $value if ($value =~ /^\s*[Ee\d\.\+-]+\s*$/);
	}
    }

    if (scalar @contents)
    {
	my $retStr = join(' ', @contents);
	return $retStr;
    }

    return undef;
}

sub comment
{
    my $self = shift;
    my $contents = shift;

    my $newEl = XML::Mini::Element::Comment->new();
    $newEl->text($contents);

    $self->appendChild($newEl);

    return $newEl;
}

sub header
{
    my $self = shift;
    my $name = shift;
    my $attribs = shift; # optional

    unless (defined $name)
    {
    	return XML::Mini->Error("XML::Mini::Element::header() must pass a NAME to create a new header");
    }

    my $newElement = XML::Mini::Element::Header->new($name);
    $self->appendChild($newElement);

    return $newElement;
}


sub docType
{
    my $self = shift;
    my $definition = shift;

    my $newElement = XML::Mini::Element::DocType->new($definition);
    $self->appendChild($newElement);

    return $newElement;
}

sub entity
{
    my $self = shift;
    my $name = shift;
    my $value = shift;

    my $newElement = XML::Mini::Element::Entity->new($name, $value);
    $self->appendChild($newElement);

    return $newElement;
}

sub cdata
{
    my $self = shift;
    my $contents = shift;
    my $newElement = XML::Mini::Element::CData->new($contents);
    $self->appendChild($newElement);

    return $newElement;
}

# Note: the seperator parameter remains officially undocumented
# since I'm not sure it will remain part of the API
sub getValue {
    my $self = shift;
    my $seperator = shift || ' ';

    my @valArray;
    my $retStr = '';

    foreach my $child ( @{$self->{'_children'}})
    {
	my $value = $child->getValue();
	if (defined $value)
	{
	    push @valArray , $value;
	}
    }

    if (scalar @valArray)
    {
	$retStr = join($seperator, @valArray);
    }

    return $retStr;
}

sub getElement {
	my $self = shift;
	my $name = shift;
	my $elementNumber = shift || 1;

	return XML::Mini->Error("Element::getElement() Must Pass Element name.")
		unless defined ($name);

	if ($XML::Mini::Debug)
	{
		XML::Mini->Log("Element::getElement() called for $name on " . $self->{'_name'} );
	}


	########## getElement needs to search the calling element's children ONLY
	########## or else it is impossible to retrieve the nested element of the same name:
	##########
	##########
	##########    The second nested element is inaccessible if we return $self...
	##########
	##########
	#if ($XML::Mini::CaseSensitive)
	#{
		#return $self if ($self->{'_name'} =~ m/^$name$/);
	#} else {
		#return $self if ($self->{'_name'} =~ m/^$name$/i);
	#}

	return undef unless $self->{'_numChildren'};

	my $foundCount = 0;
	#* Try each child (immediate children take priority) *
	for (my $i = 0; $i < $self->{'_numChildren'}; $i++)
	{
		my $childname = $self->{'_children'}->[$i]->name();
		if ($childname)
		{
		    if ($XML::Mini::CaseSensitive)
		    {
		    	if ($name =~ m/^$childname$/)
			{
				$foundCount++;
				return $self->{'_children'}->[$i] if ($foundCount == $elementNumber);
			}
		    } else {
		    	if ($name =~ m/^$childname$/i)
			{
				$foundCount++;
				return $self->{'_children'}->[$i] if ($foundCount == $elementNumber);
			}

		    }

		} #/* end if child has a name */

	} #/* end loop over all my children */

	#/* Now, Use beautiful recursion, daniel san */
	for (my $i = 0; $i < $self->{'_numChildren'}; $i++)
	{
		my $theelement = $self->{'_children'}->[$i]->getElement($name, $elementNumber);
		if ($theelement)
		{

			XML::Mini->Log("Element::getElement() returning element " . $theelement->name())
				if ($XML::Mini::Debug);

			return $theelement;
		}
	}

	#/* Not found */
	return undef;
}

sub getElementByPath
{
    my $self = shift;
    my $path = shift || return undef;
    my @elementNumbers = @_;

    my @names = split ("/", $path);
    my $element = $self;
    my $position = 0;
    foreach my $elementName (@names)
    {
	next unless ($elementName);
	if ($element) #/* Make sure we didn't hit a dead end */
	{
	    #/* Ask this element to get the next child in path */
	    $element = $element->getElement($elementName, $elementNumbers[$position++]);
	}
    }
    return $element;
} #/* end method getElementByPath */


sub numChildren
{
    my $self = shift;
    my $named = shift; # optionally only count elements named 'named'
    unless (defined $named)
    {
	return $self->{'_numElementChildren'};
    }
    my $allkids = $self->getAllChildren($named);
    return scalar @{$allkids};
}

sub getAllChildren
{
    my $self = shift;
    my $name = shift; # optionally only children with this name


    my @returnChildren;
    for (my $i=0; $i < $self->{'_numChildren'}; $i++)
    {
	if ($self->isElement($self->{'_children'}->[$i]))
	{
	    my $childName = $self->{'_children'}->[$i]->name();
	    # return only Element and derivatives children
	    if (defined $name)
	    {
		if ($XML::Mini::CaseSensitive)
		{
		    push @returnChildren, $self->{'_children'}->[$i]
			if ($name =~ /^$childName$/);
		} else {
		    # case insensitive
		    push @returnChildren, $self->{'_children'}->[$i]
			if ($name =~ /^$childName$/i);
		}
	    } else {
		# no name set, all children returned
		push @returnChildren, $self->{'_children'}->[$i];
	    } # end if name
	} # end if element
    } # end loop over all children
    return \@returnChildren;
}

sub isElement
{
    my $self = shift;
    my $element = shift || $self;
    my $type = ref $element;
    return undef unless $type;
    return 0 unless ($type =~ /^XML::Mini::Element/);
    return 1;
}

sub isNode
{
    my $self = shift;
    my $element = shift || $self;
    my $type = ref $element;
    return undef unless $type;
    return 0 unless ($type =~ /^XML::Mini::Node/);
    return 1;
}


sub insertChild {
	my $self = shift;
	my $child = shift;
	my $idx = shift || 0;



	$self->_validateChild($child);


	if ($self->{'_avoidLoops'} || $XML::Mini::AutoSetParent)
	{
		if ($self->{'_parent'} == $child)
		{
			my $childName = $child->name();
	    		return XML::Mini->Error("Element::insertChild() Tryng to append parent $childName as child of "
				    . $self->name());
		}
		$child->parent($self);
	}

	my $nextIdx = $self->{'_numChildren'};
	my $lastIdx = $nextIdx - 1;

	if ($idx > $lastIdx)
	{

		if ($idx > $nextIdx)
		{
			$idx = $lastIdx + 1;
		}
		$self->{'_children'}->[$idx] = $child;
		$self->{'_numChildren'}++;
		$self->{'_numElementChildren'}++ if ($self->isElement($child));

	} elsif ($idx >= 0)
	{
		my @removed = splice(@{$self->{'_children'}}, $idx);
		push @{$self->{'_children'}}, ($child, @removed);

		$self->{'_numChildren'}++;
		$self->{'_numElementChildren'}++ if ($self->isElement($child));
	} else {
		my $revIdx = (-1 * $idx) % $self->{'_numChildren'};
		my $newIdx = $self->{'_numChildren'} - $revIdx;

		if ($newIdx < 0)
		{
			return XML::Mini->Error("Element::insertChild() Ended up with a negative index? ($newIdx)");
		}

		return $self->insertChild($child, $newIdx);
	}

	return $child;
}


sub appendChild
{
	my $self = shift;
	my $child = shift;

	$self->_validateChild($child);

	if ($self->{'_avoidLoops'} || $XML::Mini::AutoSetParent)
	{
		if ($self->{'_parent'} == $child)
		{
			my $childName = $child->name();
	    		return XML::Mini->Error("Element::appendChild() Tryng to append parent $childName as child of "
				    . $self->name());
		}
		$child->parent($self);
	}

	$self->{'_numElementChildren'}++; #Note that we're addind a Element child

	my $idx = $self->{'_numChildren'}++;
	$self->{'_children'}->[$idx] = $child;

	return $self->{'_children'}->[$idx];
}

sub prependChild
{
	my $self = shift;
	my $child = shift;

	$self->_validateChild($child);

	if ($self->{'_avoidLoops'} || $XML::Mini::AutoSetParent)
	{
		if ($self->{'_parent'} == $child)
		{
			my $childName = $child->name();
	    		return XML::Mini->Error("Element::appendChild() Tryng to append parent $childName as child of "
				    . $self->name());
		}
		$child->parent($self);
	}

	$self->{'_numElementChildren'}++; #Note that we're addind a Element child

	my $idx = $self->{'_numChildren'}++;
	unshift(@{$self->{'_children'}}, $child);

	return $self->{'_children'}->[0];
}


sub createChild
{
    my $self = shift;
    my $name = shift;
    my $value = shift; # optionally fill child with

    unless (defined $name)
    {
	return XML::Mini->Error("Element::createChild() Must pass a NAME to createChild.");
    }

    my $child = XML::Mini::Element->new($name);

    $child = $self->appendChild($child);

    if (defined $value)
    {
	if ($value =~ m/^\s*[Ee\d\.\+-]+\s*$/)
	{
	    $child->numeric($value);
	} else {
	    $child->text($value);
	}
    }

    $child->avoidLoops($self->{'_avoidLoops'});

    return $child;
}


sub _validateChild {
	my $self = shift;
	my $child = shift;


	return XML::Mini->Error("Element:_validateChild() need to pass a non-NULL Element child")
		unless (defined $child);

	return XML::Mini->Error("Element::_validateChild() must pass an Element object to appendChild.")
		unless ($self->isElement($child));


	my $childName = $child->name();

	return XML::Mini->Error("Element::_validateChild() children must be named")
		unless (defined $childName);

	if ($child == $self)
	{
		return XML::Mini->Error("Element::_validateChild() Trying to append self as own child!");
	} elsif ( $self->{'_avoidLoops'} && $child->parent())
	{

		return XML::Mini->Error("Element::_validateChild() Trying to append a child ($childName) that already has a parent set "
		. "while avoidLoops is on - aborting");
	}

	return 1;
}


sub removeChild {
	my $self = shift;
	my $child = shift;

	unless (defined $child)
	{
		XML::Mini->Log("Element::removeChild() called without an ELEMENT parameter.");
		return undef;
	}

	unless ($self->{'_numChildren'})
	{
		return XML::Mini->Error("Element::removeChild() called for element without any children.");
	}

	my $childType = ref $child;
	unless ($childType && $childType =~ /XML::Mini::/)
	{
		# name of the child...
		# try to find it...
		my $el = $self->getElement($child);

		return XML::Mini->Error("Element::removeChild() called with element _name_ $child, but could not find any such element")
				unless ($el);

		$child = $el;
	}

	my $foundChild;
	my $idx = 0;
	while ($idx < $self->{'_numChildren'} && ! $foundChild)
	{
		if ($self->{'_children'}->[$idx] == $child)
		{
			$foundChild = $self->{'_children'}->[$idx];
		} else {
			$idx++;
		}
	}

	unless ($foundChild)
	{
		XML::Mini->Log("Element::removeChild() No matching child found.") if ($XML::Mini::Debug);
		return undef;
	}

	splice @{$self->{'_children'}}, $idx, 1;
	$self->{'_numChildren'}--;
	if ($foundChild->isElement())
	{
		$self->{'_numElementChildren'}--;
	}

	delete $foundChild->{'_parent'} ;
	return $foundChild;
}

sub removeAllChildren {
	my $self = shift;

	return undef unless ($self->{'_numChildren'});

	my $retList = $self->{'_children'};
	delete $self->{'_children'};
	$self->{'_numElementChildren'} = 0;
	$self->{'_numChildren'} = 0;

	foreach my $child (@{$retList})
	{
		delete $child->{'_parent'};
	}

	delete $self->{'_children'};
	$self->{'children'} = [];

	return $retList;
}

sub remove {
	my $self = shift;

	my $parent = $self->parent();

	unless ($parent)
	{
		XML::Mini->Log("XML::Mini::Element::remove() called for element with no parent set.  Aborting.");
		return undef;
	}

	my $removed = $parent->removeChild($self);

	return $removed;
}

sub parent {
    my $self = shift;
    my $parent = shift; # optionally set

    if (defined $parent)
    {
	return XML::Mini->Error("Element::parent(): Must pass an instance of Element to set.")
	    unless ($self->isElement($parent));
	$self->{'_parent'} = $parent;
    }
    return $self->{'_parent'};
}

sub avoidLoops
{
    my $self = shift;
    my $setTo = shift; # optionally set
    if (defined $setTo)
    {
	$self->{'_avoidLoops'} = $setTo;
    }
    return $self->{'_avoidLoops'};
}


sub toStructure {
	my $self = shift;


	my $retHash = {};
	my $contents = "";
	my $numAdded = 0;
	if ($self->{'_attributes'})
	{
		while (my ($attname, $attvalue) = each %{$self->{'_attributes'}})
		{
			$retHash->{$attname} = $attvalue;
			$numAdded++;
		}
	}

	my $numChildren = $self->{'_numChildren'} || 0;
	for (my $i=0; $i < $numChildren ; $i++)
	{
		my $thisChild = $self->{'_children'}->[$i];
		if ($self->isElement($thisChild))
		{
			my $name = $thisChild->name();
			my $struct = $thisChild->toStructure();
			my $existing = $retHash->{$name};

			if ($existing)
			{
				my $existingType = ref $existing || "";
				if ($existingType eq 'ARRAY')
				{
					push @{$existing}, $struct;
				} else {
					my $arrayRef = [$existing, $struct];
					$retHash->{$name} = $arrayRef;
				}
			} else {

				$retHash->{$name} = $struct;
			}


			$numAdded++;

		} else {
			$contents .= $thisChild->getValue();
		}
	}

	if ($numAdded)
	{
		if (length($contents))
		{
			$retHash->{'-content'} = $contents;
		}

		return $retHash;
	} else {
		return $contents;
	}

}


sub toString
{
    my $self = shift;
    my $depth = shift || 0;

    if ($depth == $XML::Mini::NoWhiteSpaces)
    {
	return $self->toStringNoWhiteSpaces();
    }

    my $retString;
    my $attribString = '';
    my $elementName = $self->{'_name'};
    my $spaces = $self->_spaceStr($depth);

    foreach my $atName (sort keys %{$self->{'_attributes'}})
    {
	$attribString .= qq|$atName="$self->{'_attributes'}->{$atName}" |;
    }

    $retString = "$spaces<$elementName";

    if ($attribString)
    {
	$attribString =~ s/\s*$//;
	$retString .= " $attribString";
    }

    if (! $self->{'_numChildren'})
    {
		$retString .= " />\n";
		return $retString;
    }

    # Else, we do have kids - sub element or nodes

    my $allChildrenAreNodes = 1;

    my $i=0;
    while ($allChildrenAreNodes && $i < $self->{'_numChildren'})
    {
    	$allChildrenAreNodes = 0 unless ($self->isNode($self->{'_children'}->[$i]));
    	$i++;
    }


    $retString .= ">";
    $retString .= "\n" unless ($allChildrenAreNodes);


    my $nextDepth = $depth + 1;

    for($i=0; $i < $self->{'_numChildren'}; $i++)
    {
	my $newStr = $self->{'_children'}->[$i]->toString($nextDepth);
	if (defined $newStr)
	{
	    if ( ! ($allChildrenAreNodes  || $newStr =~ m|\n$|) )
	    {
		$newStr .= "\n";
	    }

	    $retString .= $newStr;
	} # end if newStr returned
    } # end loop over all children

    $retString .= "$spaces" unless ($allChildrenAreNodes);

    $retString .= "\n";
    return $retString;
}

sub toStringNoWhiteSpaces
{
    my $self = shift;

    my $retString;
    my $attribString = '';
    my $elementName = $self->{'_name'};

    while (my ($atName, $atVal) = each %{$self->{'_attributes'}})
    {
	$attribString .= qq|$atName="$atVal" |;
    }

    $retString = "<$elementName";

    if ($attribString)
    {
	$attribString =~ s/\s*$//;
	$retString .= " $attribString";
    }

    if (! $self->{'_numChildren'})
    {
	$retString .= '/>';
	return $retString;
    }

    # Else, we do have kids - sub element or nodes

    $retString .= '>';

    for(my $i=0; $i < $self->{'_numChildren'}; $i++)
    {
	my $newStr = $self->{'_children'}->[$i]->toStringNoWhiteSpaces();
	$retString .= $newStr if (defined $newStr);
    } # end loop over all children

    $retString .= "";
    return $retString;
}

sub createNode
{
    my $self = shift;
    my $value = shift;

    my $newNode = XML::Mini::Node->new($value);
    return undef unless ($newNode);

    my $appendedNode = $self->appendNode($newNode);
    return $appendedNode;
}

sub appendNode
{
    my $self = shift;
    my $node = shift;

    return XML::Mini->Error("Element::appendNode() need to pass a non-NULL XML::MiniNode.")
	unless (defined $node);

    return XML::Mini->Error("Element::appendNode() must pass a XML::MiniNode object to appendNode.")
	unless ($self->isNode($node));



    if ($XML::Mini::AutoSetParent)
    {
	$node->parent($self);
    }

    if ($XML::Mini::Debug)
    {
	XML::Mini->Log("Appending node to " . $self->{'_name'});
      }

    my $idx = $self->{'_numChildren'}++;
    $self->{'_children'}->[$idx] = $node;

    return $self->{'_children'}->[$idx];
}

1;

__END__