view release on metacpan or  search on metacpan

lib/CAM/XML.pm  view on Meta::CPAN

=item $self->getChildNodes()

Returns an array of XML nodes contained by this node (that is, unlike
getChildren(), text nodes are ignored).

=cut

sub getChildNodes
{
   my $self = shift;

   return grep { $_->isa(__PACKAGE__) } @{ $self->{children} };
}

=item $self->getChildNode($index)

Returns a CAM::XML child of this node (that is, unlike getChild(),
text nodes are ignored.  The argument is a zero-based index.  Returns
undef if the index is not valid.

=cut

sub getChildNode
{
   my $self  = shift;
   my $index = shift;

   return if (!defined $index || $index !~ m/\A\d+\z/xms);
   my @kids = grep { $_->isa(__PACKAGE__) } @{ $self->{children} };
   return $kids[$index];
}

=item $self->setChildren($node1, $node2, ...)

Removes all the children from this node and replaces them with the
supplied values.  All of the values MUST be CAM::XML or CAM::XML::Text
objects, or this method will abort and return false before any changes
are made.

=cut

sub setChildren
{
   my $self = shift;

   my @good = grep { defined $_ && ref $_ && 
                     ($_->isa(__PACKAGE__) || $_->isa('CAM::XML::Text')) } @_;
   if (@good != @_)
   {
      croak 'Attempted to add bogus XML node';
   }

   @{ $self->{children} } = @good;
   return $self;
}

=item $self->add(CAM::XML instance)

=item $self->add(-text => $text)

=item $self->add(-cdata => $text)

=item $self->add(-xml => $rawxml)

=item $self->add(<multiple elements of the above types>)

Add content within the current tag.  Order of addition may be
significant.  This content can be any one of 1) subsidiary XML tags
(CAM::XML), 2) literal text content (C<-text> or C<-cdata>), or 3)
pre-formatted XML content (C<-xml>).

In C<-text> and C<-cdata> content, any reserved characters will be
automatically escaped.  Those two modes differ only in their XML
representation: C<-cdata> is more human-readable if there are a lot of
"&", "<" and ">" characters in your text, where C<-text> is usually more
compact for short strings.  These strings are not escaped until
output.

Content in C<-xml> mode is parsed in as CAM::XML objects.  If it is not
valid XML, a warning will be emitted and the add will fail.

=cut

sub add
{
   my $self = shift;

   while (@_ > 0)
   {
      my $add = shift;

      # Test different kinds of input
        !$add                                   ? croak 'Undefined object'
      : ref $add && $add->isa(__PACKAGE__)      ? push @{ $self->{children} }, $add
      : ref $add && $add->isa('CAM::XML::Text') ? push @{ $self->{children} }, $add
      : ref $add                                ? croak 'Invalid object type to add to a CAM::XML node'
      : $add =~ m/\A-(text|cdata)\z/xms         ? $self->_add_text($1, shift)
      : $add eq '-xml'                          ? $self->_add_xml(shift)
      : croak "Unknown flag '$add'.  Expected '-text' or '-cdata' or '-xml'";
   }

   return $self;
}

sub _add_text
{
   my $self = shift;
   my $type = shift;
   my $text = shift;

   if (!defined $text)
   {
      $text = q{};
   }
   
   # If the previous element was the same kind of text item
   # then merge them.  Otherwise append this text item.
   
   if (@{ $self->{children} } > 0 &&
       $self->{children}->[-1]->isa('CAM::XML::Text') &&
       $self->{children}->[-1]->{type} eq $type)
   {
      $self->{children}->[-1]->{text} .= $text;
   }
   else
   {
      push @{ $self->{children} }, CAM::XML::Text->new($type => $text);
   }
   return;
}

sub _add_xml
{
   my $self = shift;
   my $xml  = shift;

   my $parsed = $self->parse($xml);
   if ($parsed)
   {
      $self->add($parsed);
   }
   else
   {
      croak 'Tried to add invalid XML content';
   }
   return;
}

=item $self->removeWhitespace()

Clean out all non-significant whitespace.  Whitespace is deemed
non-significant if it is bracketed by tags.  This might not be true in
some data formats (e.g. HTML) so don't use this function carelessly.

=cut

sub removeWhitespace
{
   my $self = shift;