Net/XMPP2/Node.pm

package Net::XMPP2::Node;
use warnings;
use strict;
use Net::XMPP2::Namespaces qw/xmpp_ns/;

use constant {
   NS     => 0,
   NAME   => 1,
   ATTRS  => 2,
   TEXT   => 3,
   NODES  => 4,
   PARSER => 5,
};

=head1 NAME

Net::XMPP2::Node - A XML node tree helper for the parser.

=head1 SYNOPSIS

   use Net::XMPP2::Node;
   ...

=head1 DESCRIPTION

This class represens a XML node. L<Net::XMPP2> should usually not
require messing with the parse tree, but sometimes it is neccessary.

If you experience any need for messing with these and feel L<Net::XMPP2> should
rather take care of it drop me a mail, feature request or most preferably a patch!

Every L<Net::XMPP2::Node> has a namespace, attributes, text and child nodes.

You can access these with the following methods:

=head1 METHODS

=over 4

=item B<new ($ns, $el, $attrs, $parser)>

Creates a new Net::XMPP2::Node object with the node tag name C<$el> in the
namespace URI C<$ns> and the attributes C<$attrs>. The C<$parser> must be
the instance of C<Net::XMPP2::Parser> which generated this node.

=cut

sub new {
   my $this = shift;
   my $class = ref($this) || $this;
   my $self = [];
   $self->[0] = $_[0];
   $self->[1] = $_[1];
   $self->[2] = $_[2];
   $self->[5] = $_[3];
   bless $self, $class;
   return $self
}

=item B<name>

The tag name of this node.

=cut

sub name {
   $_[0]->[NAME]
}

=item B<namespace>

Returns the namespace URI of this node.

=cut

sub namespace {
   $_[0]->[NS]
}

=item B<eq ($namespace_or_alias, $name) or eq ($node)>

Returns true whether the current element matches the tag name C<$name>
in the namespaces pointed at by C<$namespace_or_alias>.

You can either pass an alias that was defined in L<Net::XMPP2::Namespaces>
or pass an namespace URI in C<$namespace_or_alias>. If no alias with the name
C<$namespace_or_alias> was found in L<Net::XMPP2::Namespaces> it will be
interpreted as namespace URI.

The first argument to eq can also be another L<Net::XMPP2::Node> instance.

=cut

sub eq {
   my ($self, $n, $name) = @_;
   if (ref $n) {
      return $self->[PARSER]->nseq ($n->namespace, $n->name, $self->name);
   } else {
      my $ns = xmpp_ns ($n);
      return $self->[PARSER]->nseq (($ns ? $ns : $n), $name, $self->name);
   }
}

=item B<eq_ns ($namespace_or_alias) or eq_ns ($node)>

This method return true if the namespace of this instance of L<Net::XMPP2::Node>
matches the namespace described by C<$namespace_or_alias> or the
namespace of the C<$node> which has to be another L<Net::XMPP2::Node> instance.

See C<eq> for the meaning of C<$namespace_or_alias>.

=cut

sub eq_ns {
   my ($self, $n) = @_;
   if (ref $n) {
      return ($n->namespace eq $self->namespace);
   } else {
      my $ns = xmpp_ns ($n);
      $ns ||= $n;
      return ($ns eq $self->namespace);
   }
}

=item B<attr ($name)>

Returns the contents of the C<$name> attribute.

=cut

sub attr {
   $_[0]->[ATTRS]->{$_[1]};
}

=item B<add_node ($node)>

Adds a sub-node to the current node.

=cut

sub add_node {
   my ($self, $node) = @_;
   push @{$self->[NODES]}, $node;
}

=item B<nodes>

Returns a list of sub nodes.

=cut

sub nodes {
   @{$_[0]->[NODES] || []};
}

=item B<add_text ($string)>

Adds character data to the current node.

=cut

sub add_text {
   my ($self, $text) = @_;
   $self->[TEXT] .= $text;
}

=item B<text>

Returns the text for this node.

=cut

sub text {
   $_[0]->[TEXT];
}

=item B<find_all (@path)>

This method does a recursive descent through the sub-nodes and
fetches all nodes that match the last element of C<@path>.

The elements of C<@path> consist of a array reference to an array with
two elements: the namespace key known by the C<$parser> and the tagname
we search for.

=cut

sub find_all {
   my ($self, @path) = @_;
   my $cur = shift @path;
   my @ret;
   for my $n ($self->nodes) {
      if ($n->eq (@$cur)) {
         if (@path) {
            push @ret, $n->find_all (@path);
         } else {
            push @ret, $n;
         }
      }
   }
   @ret
}

=item B<write_on ($writer)>

This writes the current node out to the L<Net::XMPP2::Writer> object in C<$writer>.

=cut

sub write_on {
   my ($self, $w) = @_;

   my ($ns, $tag) = ($self->namespace, $self->name);
   $w->addPrefix ($ns => ''); # omg, xmpp is soo broken...
   if ($self->nodes) {
      $w->startTag ([$ns, $tag], %{$self->[ATTRS]});
      $_->write_on ($w) for $self->nodes;
      $w->endTag;
   } else {
      $w->emptyTag ([$ns, $tag], %{$self->[ATTRS]});
   }
}

=back

=head1 AUTHOR

Robin Redeker, C<< <elmex at ta-sa.org> >>, JID: C<< <elmex at jabber.org> >>

=head1 COPYRIGHT & LICENSE

Copyright 2007 Robin Redeker, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

1; # End of Net::XMPP2
Revision:	1.4
Committed:	Wed Jul 4 16:05:22 2007 UTC (19 years, 2 months ago) by elmex
Branch:	MAIN
Changes since 1.3:	+29 -13 lines
Log Message:	major documentation refresh. preparing for release
#	User	Rev	Content
1	elmex	1.1	package Net::XMPP2::Node;
2			use warnings;
3			use strict;
4			use Net::XMPP2::Namespaces qw/xmpp_ns/;
5
6			use constant {
7			NS => 0,
8			NAME => 1,
9			ATTRS => 2,
10			TEXT => 3,
11			NODES => 4,
12			PARSER => 5,
13			};
14
15			=head1 NAME
16
17			Net::XMPP2::Node - A XML node tree helper for the parser.
18
19			=head1 SYNOPSIS
20
21			use Net::XMPP2::Node;
22			...
23
24	elmex	1.4	=head1 DESCRIPTION
25
26			This class represens a XML node. L<Net::XMPP2> should usually not
27			require messing with the parse tree, but sometimes it is neccessary.
28
29			If you experience any need for messing with these and feel L<Net::XMPP2> should
30			rather take care of it drop me a mail, feature request or most preferably a patch!
31
32			Every L<Net::XMPP2::Node> has a namespace, attributes, text and child nodes.
33
34			You can access these with the following methods:
35
36	elmex	1.1	=head1 METHODS
37
38	elmex	1.4	=over 4
39
40			=item B<new ($ns, $el, $attrs, $parser)>
41	elmex	1.1
42			Creates a new Net::XMPP2::Node object with the node tag name C<$el> in the
43			namespace URI C<$ns> and the attributes C<$attrs>. The C<$parser> must be
44			the instance of C<Net::XMPP2::Parser> which generated this node.
45
46			=cut
47
48			sub new {
49			my $this = shift;
50			my $class = ref($this) \|\| $this;
51			my $self = [];
52			$self->[0] = $_[0];
53			$self->[1] = $_[1];
54			$self->[2] = $_[2];
55			$self->[5] = $_[3];
56			bless $self, $class;
57			return $self
58			}
59
60	elmex	1.4	=item B<name>
61	elmex	1.1
62			The tag name of this node.
63
64			=cut
65
66			sub name {
67			$_[0]->[NAME]
68			}
69
70	elmex	1.4	=item B<namespace>
71	elmex	1.1
72			Returns the namespace URI of this node.
73
74			=cut
75
76			sub namespace {
77			$_[0]->[NS]
78			}
79
80	elmex	1.4	=item B<eq ($namespace_or_alias, $name) or eq ($node)>
81	elmex	1.1
82			Returns true whether the current element matches the tag name C<$name>
83			in the namespaces pointed at by C<$namespace_or_alias>.
84
85			You can either pass an alias that was defined in L<Net::XMPP2::Namespaces>
86			or pass an namespace URI in C<$namespace_or_alias>. If no alias with the name
87			C<$namespace_or_alias> was found in L<Net::XMPP2::Namespaces> it will be
88			interpreted as namespace URI.
89
90			The first argument to eq can also be another L<Net::XMPP2::Node> instance.
91
92			=cut
93
94			sub eq {
95			my ($self, $n, $name) = @_;
96			if (ref $n) {
97			return $self->[PARSER]->nseq ($n->namespace, $n->name, $self->name);
98			} else {
99			my $ns = xmpp_ns ($n);
100			return $self->[PARSER]->nseq (($ns ? $ns : $n), $name, $self->name);
101			}
102			}
103
104	elmex	1.4	=item B<eq_ns ($namespace_or_alias) or eq_ns ($node)>
105	elmex	1.1
106			This method return true if the namespace of this instance of L<Net::XMPP2::Node>
107			matches the namespace described by C<$namespace_or_alias> or the
108			namespace of the C<$node> which has to be another L<Net::XMPP2::Node> instance.
109
110			See C<eq> for the meaning of C<$namespace_or_alias>.
111
112			=cut
113
114			sub eq_ns {
115			my ($self, $n) = @_;
116			if (ref $n) {
117			return ($n->namespace eq $self->namespace);
118			} else {
119			my $ns = xmpp_ns ($n);
120			$ns \|\|= $n;
121			return ($ns eq $self->namespace);
122			}
123			}
124
125	elmex	1.4	=item B<attr ($name)>
126	elmex	1.1
127			Returns the contents of the C<$name> attribute.
128
129			=cut
130
131			sub attr {
132			$_[0]->[ATTRS]->{$_[1]};
133			}
134
135	elmex	1.4	=item B<add_node ($node)>
136	elmex	1.1
137			Adds a sub-node to the current node.
138
139			=cut
140
141			sub add_node {
142			my ($self, $node) = @_;
143			push @{$self->[NODES]}, $node;
144			}
145
146	elmex	1.4	=item B<nodes>
147	elmex	1.1
148			Returns a list of sub nodes.
149
150			=cut
151
152			sub nodes {
153			@{$_[0]->[NODES] \|\| []};
154			}
155
156	elmex	1.4	=item B<add_text ($string)>
157	elmex	1.1
158			Adds character data to the current node.
159
160			=cut
161
162			sub add_text {
163			my ($self, $text) = @_;
164			$self->[TEXT] .= $text;
165			}
166
167	elmex	1.4	=item B<text>
168	elmex	1.1
169			Returns the text for this node.
170
171			=cut
172
173			sub text {
174			$_[0]->[TEXT];
175			}
176
177	elmex	1.4	=item B<find_all (@path)>
178	elmex	1.1
179			This method does a recursive descent through the sub-nodes and
180			fetches all nodes that match the last element of C<@path>.
181
182			The elements of C<@path> consist of a array reference to an array with
183			two elements: the namespace key known by the C<$parser> and the tagname
184			we search for.
185
186			=cut
187
188			sub find_all {
189			my ($self, @path) = @_;
190			my $cur = shift @path;
191			my @ret;
192			for my $n ($self->nodes) {
193			if ($n->eq (@$cur)) {
194			if (@path) {
195			push @ret, $n->find_all (@path);
196			} else {
197			push @ret, $n;
198			}
199			}
200			}
201			@ret
202			}
203
204	elmex	1.4	=item B<write_on ($writer)>
205	elmex	1.2
206			This writes the current node out to the L<Net::XMPP2::Writer> object in C<$writer>.
207
208			=cut
209
210			sub write_on {
211			my ($self, $w) = @_;
212
213			my ($ns, $tag) = ($self->namespace, $self->name);
214			$w->addPrefix ($ns => ''); # omg, xmpp is soo broken...
215			if ($self->nodes) {
216			$w->startTag ([$ns, $tag], %{$self->[ATTRS]});
217			$_->write_on ($w) for $self->nodes;
218			$w->endTag;
219			} else {
220			$w->emptyTag ([$ns, $tag], %{$self->[ATTRS]});
221			}
222			}
223
224	elmex	1.4	=back
225
226	elmex	1.1	=head1 AUTHOR
227
228	elmex	1.4	Robin Redeker, C<< <elmex at ta-sa.org> >>, JID: C<< <elmex at jabber.org> >>
229	elmex	1.1
230			=head1 COPYRIGHT & LICENSE
231
232			Copyright 2007 Robin Redeker, all rights reserved.
233
234			This program is free software; you can redistribute it and/or modify it
235			under the same terms as Perl itself.
236
237			=cut
238
239			1; # End of Net::XMPP2