local-lib5/lib/perl5/i486-linux-gnu-thread-multi/XML/LibXML/NodeList.pm

   1 # $Id: NodeList.pm 785 2009-07-16 14:17:46Z pajas $
   2 #
   3 # This is free software, you may use it and distribute it under the same terms as
   4 # Perl itself.
   5 #
   6 # Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
   7 #
   8 #
   9
  10 package XML::LibXML::NodeList;
  11 use strict;
  12 use XML::LibXML::Boolean;
  13 use XML::LibXML::Literal;
  14 use XML::LibXML::Number;
  15
  16 use vars qw ($VERSION);
  17 $VERSION = "1.70"; # VERSION TEMPLATE: DO NOT CHANGE
  18
  19 use overload
  20                 '""' => \&to_literal,
  21                 'bool' => \&to_boolean,
  22         ;
  23
  24 sub new {
  25         my $class = shift;
  26         bless [@_], $class;
  27 }
  28
  29 sub new_from_ref {
  30         my ($class,$array_ref,$reuse) = @_;
  31         return bless $reuse ? $array_ref : [@$array_ref], $class;
  32 }
  33
  34 sub pop {
  35         my $self = CORE::shift;
  36         CORE::pop @$self;
  37 }
  38
  39 sub push {
  40         my $self = CORE::shift;
  41         CORE::push @$self, @_;
  42 }
  43
  44 sub append {
  45         my $self = CORE::shift;
  46         my ($nodelist) = @_;
  47         CORE::push @$self, $nodelist->get_nodelist;
  48 }
  49
  50 sub shift {
  51         my $self = CORE::shift;
  52         CORE::shift @$self;
  53 }
  54
  55 sub unshift {
  56         my $self = CORE::shift;
  57         CORE::unshift @$self, @_;
  58 }
  59
  60 sub prepend {
  61         my $self = CORE::shift;
  62         my ($nodelist) = @_;
  63         CORE::unshift @$self, $nodelist->get_nodelist;
  64 }
  65
  66 sub size {
  67         my $self = CORE::shift;
  68         scalar @$self;
  69 }
  70
  71 sub get_node {
  72     # uses array index starting at 1, not 0
  73     # this is mainly because of XPath.
  74         my $self = CORE::shift;
  75         my ($pos) = @_;
  76         $self->[$pos - 1];
  77 }
  78
  79 *item = \&get_node;
  80
  81 sub get_nodelist {
  82         my $self = CORE::shift;
  83         @$self;
  84 }
  85
  86 sub to_boolean {
  87         my $self = CORE::shift;
  88         return (@$self > 0) ? XML::LibXML::Boolean->True : XML::LibXML::Boolean->False;
  89 }
  90
  91 # string-value of a nodelist is the string-value of the first node
  92 sub string_value {
  93         my $self = CORE::shift;
  94         return '' unless @$self;
  95         return $self->[0]->string_value;
  96 }
  97
  98 sub to_literal {
  99         my $self = CORE::shift;
 100         return XML::LibXML::Literal->new(
 101                         join('', grep {defined $_} map { $_->string_value } @$self)
 102                         );
 103 }
 104
 105 sub to_number {
 106         my $self = CORE::shift;
 107         return XML::LibXML::Number->new(
 108                         $self->to_literal
 109                         );
 110 }
 111
 112 sub iterator {
 113     warn "this function is obsolete!\nIt was disabled in version 1.54\n";
 114     return undef;
 115 }
 116
 117 1;
 118 __END__
 119
 120 =head1 NAME
 121
 122 XML::LibXML::NodeList - a list of XML document nodes
 123
 124 =head1 DESCRIPTION
 125
 126 An XML::LibXML::NodeList object contains an ordered list of nodes, as
 127 detailed by the W3C DOM documentation of Node Lists.
 128
 129 =head1 SYNOPSIS
 130
 131   my $results = $dom->findnodes('//somepath');
 132   foreach my $context ($results->get_nodelist) {
 133     my $newresults = $context->findnodes('./other/element');
 134     ...
 135   }
 136
 137 =head1 API
 138
 139 =head2 new()
 140
 141 You will almost never have to create a new NodeSet object, as it is all
 142 done for you by XPath.
 143
 144 =head2 get_nodelist()
 145
 146 Returns a list of nodes, the contents of the node list, as a perl list.
 147
 148 =head2 string_value()
 149
 150 Returns the string-value of the first node in the list.
 151 See the XPath specification for what "string-value" means.
 152
 153 =head2 to_literal()
 154
 155 Returns the concatenation of all the string-values of all
 156 the nodes in the list.
 157
 158 =head2 get_node($pos)
 159
 160 Returns the node at $pos. The node position in XPath is based at 1, not 0.
 161
 162 =head2 size()
 163
 164 Returns the number of nodes in the NodeSet.
 165
 166 =head2 pop()
 167
 168 Equivalent to perl's pop function.
 169
 170 =head2 push(@nodes)
 171
 172 Equivalent to perl's push function.
 173
 174 =head2 append($nodelist)
 175
 176 Given a nodelist, appends the list of nodes in $nodelist to the end of the
 177 current list.
 178
 179 =head2 shift()
 180
 181 Equivalent to perl's shift function.
 182
 183 =head2 unshift(@nodes)
 184
 185 Equivalent to perl's unshift function.
 186
 187 =head2 prepend($nodeset)
 188
 189 Given a nodelist, prepends the list of nodes in $nodelist to the front of
 190 the current list.
 191
 192 =head2 iterator()
 193
 194 Will return a new nodelist iterator for the current nodelist. A
 195 nodelist iterator is usefull if more complex nodelist processing is
 196 needed.
 197
 198 =cut