view release on metacpan or  search on metacpan

lib/XML/Mini/Element.pm  view on Meta::CPAN

	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:
	########## <nested>
	##########  <nested>
	##########    The second nested element is inaccessible if we return $self...
	##########  </nested>
	########## <nested>
	#if ($XML::Mini::CaseSensitive)
	#{
		#return $self if ($self->{'_name'} =~ m/^$name$/);
	#} else {

lib/XML/Mini/Element.pm  view on Meta::CPAN

If the optional SETTOALT is passed and SETTO is false, the 
new node's value is set to SETTOALT.  See the attribute() method
for an example use.

Returns a space seperated string composed all child XML::MiniNodes' 
numeric contents.

Note: ONLY numerical contents are included from the list of child XML::MiniNodes.

=head2 header NAME

The header() method allows you to add a new XML::Mini::Element::Header to this 
element's list of children.

Headers return a <? NAME ?> string for the element's toString() method.  Attributes
may be set using attribute(), to create headers like
<?xml-stylesheet href="doc.xsl" type="text/xsl"?>

Valid XML documents must have at least an 'xml' header, like:
<?xml version="1.0" ?>

Here's how you could begin creating an XML document:

 

	my $miniXMLDoc =  XML::Mini::Document->new();
	my $xmlRootNode = $miniXMLDoc->getRoot();
	my $xmlHeader = $xmlRootNode->header('xml');
	$xmlHeader->attribute('version', '1.0');

This method was added in version 1.25.

=head2 comment CONTENTS

The comment() method allows you to add a new XML::Mini::Element::Comment to this
element's list of children.

Comments will return a <!-- CONTENTS --> string when the element's toString()
method is called.

Returns a reference to the newly appended XML::Mini::Element::Comment

=head2 docType DEFINITION

Append a new <!DOCTYPE DEFINITION [ ...]> element as a child of this 
element.

Returns the appended DOCTYPE element. You will normally use the returned
element to add ENTITY elements, like

 my $newDocType = $xmlRoot->docType('spec SYSTEM "spec.dtd"');
 $newDocType->entity('doc.audience', 'public review and discussion');

=head2 entity NAME VALUE

Append a new <!ENTITY NAME "VALUE"> element as a child of this 
element.

Returns the appended ENTITY element.

=head2 cdata CONTENTS

Append a new <![CDATA[ CONTENTS ]]> element as a child of this element.
Returns the appended CDATA element.

=head2 getValue

Returns a string containing the value of all the element's
child XML::MiniNodes (and all the XML::MiniNodes contained within 
it's child Elements, recursively).


=head2 getElement NAME [POSITION]

Searches the element and it's children for an element with name NAME.

Returns a reference to the first Element with name NAME,
if found, NULL otherwise.

NOTE: The search is performed like this, returning the first 
	 element that matches:
 

 - Check this element's immediate children (in order) for a match.
 - Ask each immediate child (in order) to Element::getElement()
  (each child will then proceed similarly, checking all it's immediate
  children in order and then asking them to getElement())


If a numeric POSITION parameter is passed, getElement() will return 
the POSITIONth element of name NAME (starting at 1).  Thus, on document
 

  <?xml version="1.0"?>
  <people>
   <person>
    bob
   </person>
   <person>
    jane
   </person>
   <person>
    ralph
   </person>
  </people>

$people->getElement('person') will return the element containing the text node
'bob', while $people->getElement('person', 3) will return the element containing the 
text 'ralph'.




=head2 getElementByPath PATH [POSITIONSARRAY]


Attempts to return a reference to the (first) element at PATH
where PATH is the path in the structure (relative to this element) to
the requested element.

For example, in the document represented by: