← Index
NYTProf Performance Profile   « line view »
For svc/members/upsert
  Run on Tue Jan 13 11:50:22 2015
Reported on Tue Jan 13 12:09:47 2015

Filename/usr/share/perl5/XML/NamespaceSupport.pm
StatementsExecuted 3651 statements in 3.54ms
Subroutines
Calls P F Exclusive
Time		 Inclusive
Time		 Subroutine
19821588µs588µsXML::NamespaceSupport::::_get_ns_detailsXML::NamespaceSupport::_get_ns_details
14211346µs756µsXML::NamespaceSupport::::process_element_nameXML::NamespaceSupport::process_element_name
14211335µs335µsXML::NamespaceSupport::::push_contextXML::NamespaceSupport::push_context
14211171µs171µsXML::NamespaceSupport::::pop_contextXML::NamespaceSupport::pop_context
5611145µs322µsXML::NamespaceSupport::::process_attribute_nameXML::NamespaceSupport::process_attribute_name
81149µs49µsXML::NamespaceSupport::::declare_prefixXML::NamespaceSupport::declare_prefix
21116µs16µsXML::NamespaceSupport::::newXML::NamespaceSupport::new
11111µs22µsXML::NamespaceSupport::::BEGIN@8XML::NamespaceSupport::BEGIN@8
11110µs202µsXML::NamespaceSupport::::BEGIN@9XML::NamespaceSupport::BEGIN@9
11110µs23µsXML::NamespaceSupport::::BEGIN@99XML::NamespaceSupport::BEGIN@99
1117µs27µsXML::NamespaceSupport::::BEGIN@15XML::NamespaceSupport::BEGIN@15
1117µs38µsXML::NamespaceSupport::::BEGIN@18XML::NamespaceSupport::BEGIN@18
1116µs23µsXML::NamespaceSupport::::BEGIN@110XML::NamespaceSupport::BEGIN@110
1116µs28µsXML::NamespaceSupport::::BEGIN@10XML::NamespaceSupport::BEGIN@10
1116µs25µsXML::NamespaceSupport::::BEGIN@11XML::NamespaceSupport::BEGIN@11
1115µs24µsXML::NamespaceSupport::::BEGIN@12XML::NamespaceSupport::BEGIN@12
1115µs24µsXML::NamespaceSupport::::BEGIN@14XML::NamespaceSupport::BEGIN@14
1115µs23µsXML::NamespaceSupport::::BEGIN@13XML::NamespaceSupport::BEGIN@13
1115µs23µsXML::NamespaceSupport::::BEGIN@16XML::NamespaceSupport::BEGIN@16
0000s0sXML::NamespaceSupport::::declare_prefixesXML::NamespaceSupport::declare_prefixes
0000s0sXML::NamespaceSupport::::get_declared_prefixesXML::NamespaceSupport::get_declared_prefixes
0000s0sXML::NamespaceSupport::::get_prefixXML::NamespaceSupport::get_prefix
0000s0sXML::NamespaceSupport::::get_prefixesXML::NamespaceSupport::get_prefixes
0000s0sXML::NamespaceSupport::::get_uriXML::NamespaceSupport::get_uri
0000s0sXML::NamespaceSupport::::parse_jclark_notationXML::NamespaceSupport::parse_jclark_notation
0000s0sXML::NamespaceSupport::::process_nameXML::NamespaceSupport::process_name
0000s0sXML::NamespaceSupport::::resetXML::NamespaceSupport::reset
0000s0sXML::NamespaceSupport::::undeclare_prefixXML::NamespaceSupport::undeclare_prefix
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments		 Time
on line		 Calls Time
in subs		 Code
1
2###
3# XML::NamespaceSupport - a simple generic namespace processor
4# Robin Berjon <robin@knowscape.com>
5###
6
7package XML::NamespaceSupport;
8224µs234µs
# spent 22µs (11+12) within XML::NamespaceSupport::BEGIN@8 which was called: # once (11µs+12µs) by XML::SAX::Expat::BEGIN@10 at line 8
use strict;
# spent 22µs making 1 call to XML::NamespaceSupport::BEGIN@8 # spent 12µs making 1 call to strict::import
9229µs2394µs
# spent 202µs (10+192) within XML::NamespaceSupport::BEGIN@9 which was called: # once (10µs+192µs) by XML::SAX::Expat::BEGIN@10 at line 9
use constant FATALS => 0; # root object
# spent 202µs making 1 call to XML::NamespaceSupport::BEGIN@9 # spent 192µs making 1 call to constant::import
10222µs251µs
# spent 28µs (6+23) within XML::NamespaceSupport::BEGIN@10 which was called: # once (6µs+23µs) by XML::SAX::Expat::BEGIN@10 at line 10
use constant NSMAP => 1;
# spent 28µs making 1 call to XML::NamespaceSupport::BEGIN@10 # spent 23µs making 1 call to constant::import
11221µs244µs
# spent 25µs (6+19) within XML::NamespaceSupport::BEGIN@11 which was called: # once (6µs+19µs) by XML::SAX::Expat::BEGIN@10 at line 11
use constant UNKNOWN_PREF => 2;
# spent 25µs making 1 call to XML::NamespaceSupport::BEGIN@11 # spent 19µs making 1 call to constant::import
12220µs243µs
# spent 24µs (5+19) within XML::NamespaceSupport::BEGIN@12 which was called: # once (5µs+19µs) by XML::SAX::Expat::BEGIN@10 at line 12
use constant AUTO_PREFIX => 3;
# spent 24µs making 1 call to XML::NamespaceSupport::BEGIN@12 # spent 19µs making 1 call to constant::import
13220µs242µs
# spent 23µs (5+18) within XML::NamespaceSupport::BEGIN@13 which was called: # once (5µs+18µs) by XML::SAX::Expat::BEGIN@10 at line 13
use constant XMLNS_11 => 4;
# spent 23µs making 1 call to XML::NamespaceSupport::BEGIN@13 # spent 18µs making 1 call to constant::import
14220µs243µs
# spent 24µs (5+19) within XML::NamespaceSupport::BEGIN@14 which was called: # once (5µs+19µs) by XML::SAX::Expat::BEGIN@10 at line 14
use constant DEFAULT => 0; # maps
# spent 24µs making 1 call to XML::NamespaceSupport::BEGIN@14 # spent 19µs making 1 call to constant::import
15220µs247µs
# spent 27µs (7+20) within XML::NamespaceSupport::BEGIN@15 which was called: # once (7µs+20µs) by XML::SAX::Expat::BEGIN@10 at line 15
use constant PREFIX_MAP => 1;
# spent 27µs making 1 call to XML::NamespaceSupport::BEGIN@15 # spent 20µs making 1 call to constant::import
16222µs241µs
# spent 23µs (5+18) within XML::NamespaceSupport::BEGIN@16 which was called: # once (5µs+18µs) by XML::SAX::Expat::BEGIN@10 at line 16
use constant DECLARATIONS => 2;
# spent 23µs making 1 call to XML::NamespaceSupport::BEGIN@16 # spent 18µs making 1 call to constant::import
17
182292µs269µs
# spent 38µs (7+31) within XML::NamespaceSupport::BEGIN@18 which was called: # once (7µs+31µs) by XML::SAX::Expat::BEGIN@10 at line 18
use vars qw($VERSION $NS_XMLNS $NS_XML);
# spent 38µs making 1 call to XML::NamespaceSupport::BEGIN@18 # spent 31µs making 1 call to vars::import
191400ns$VERSION = '1.11';
201200ns$NS_XMLNS = 'http://www.w3.org/2000/xmlns/';
211100ns$NS_XML = 'http://www.w3.org/XML/1998/namespace';
22
23
24# add the ns stuff that baud wants based on Java's xml-writer
25
26
27#-------------------------------------------------------------------#
28# constructor
29#-------------------------------------------------------------------#
30
# spent 16µs within XML::NamespaceSupport::new which was called 2 times, avg 8µs/call: # 2 times (16µs+0s) by XML::SAX::Expat::_create_parser at line 123 of XML/SAX/Expat.pm, avg 8µs/call
sub new {
3121µs my $class = ref($_[0]) ? ref(shift) : shift;
322400ns my $options = shift;
3326µs my $self = [
34 1, # FATALS
35 [[ # NSMAP
36 undef, # DEFAULT
37 { xml => $NS_XML }, # PREFIX_MAP
38 undef, # DECLARATIONS
39 ]],
40 'aaa', # UNKNOWN_PREF
41 0, # AUTO_PREFIX
42 1, # XML_11
43 ];
4423µs $self->[NSMAP]->[0]->[PREFIX_MAP]->{xmlns} = $NS_XMLNS if $options->{xmlns};
452700ns $self->[FATALS] = $options->{fatal_errors} if defined $options->{fatal_errors};
462800ns $self->[AUTO_PREFIX] = $options->{auto_prefix} if defined $options->{auto_prefix};
472500ns $self->[XMLNS_11] = $options->{xmlns_11} if defined $options->{xmlns_11};
4826µs return bless $self, $class;
49}
50#-------------------------------------------------------------------#
51
52#-------------------------------------------------------------------#
53# reset() - return to the original state (for reuse)
54#-------------------------------------------------------------------#
55sub reset {
56 my $self = shift;
57 $#{$self->[NSMAP]} = 0;
58}
59#-------------------------------------------------------------------#
60
61#-------------------------------------------------------------------#
62# push_context() - add a new empty context to the stack
63#-------------------------------------------------------------------#
64
# spent 335µs within XML::NamespaceSupport::push_context which was called 142 times, avg 2µs/call: # 142 times (335µs+0s) by XML::SAX::Expat::_handle_start at line 184 of XML/SAX/Expat.pm, avg 2µs/call
sub push_context {
6514214µs my $self = shift;
66 push @{$self->[NSMAP]}, [
67 $self->[NSMAP]->[-1]->[DEFAULT],
68142431µs { %{$self->[NSMAP]->[-1]->[PREFIX_MAP]} },
69 [],
70 ];
71}
72#-------------------------------------------------------------------#
73
74#-------------------------------------------------------------------#
75# pop_context() - remove the topmost context fromt the stack
76#-------------------------------------------------------------------#
77
# spent 171µs within XML::NamespaceSupport::pop_context which was called 142 times, avg 1µs/call: # 142 times (171µs+0s) by XML::SAX::Expat::_handle_end at line 243 of XML/SAX/Expat.pm, avg 1µs/call
sub pop_context {
7814218µs my $self = shift;
7914243µs die 'Trying to pop context without push context' unless @{$self->[NSMAP]} > 1;
80142179µs pop @{$self->[NSMAP]};
81}
82#-------------------------------------------------------------------#
83
84#-------------------------------------------------------------------#
85# declare_prefix() - declare a prefix in the current scope
86#-------------------------------------------------------------------#
87
# spent 49µs within XML::NamespaceSupport::declare_prefix which was called 8 times, avg 6µs/call: # 8 times (49µs+0s) by XML::SAX::Expat::_handle_start at line 189 of XML/SAX/Expat.pm, avg 6µs/call
sub declare_prefix {
8881µs my $self = shift;
8981µs my $prefix = shift;
9081µs my $value = shift;
91
9282µs warn <<' EOWARN' unless defined $prefix or $self->[AUTO_PREFIX];
93 Prefix was undefined.
94 If you wish to set the default namespace, use the empty string ''.
95 If you wish to autogenerate prefixes, set the auto_prefix option
96 to a true value.
97 EOWARN
98
99276µs237µs
# spent 23µs (10+14) within XML::NamespaceSupport::BEGIN@99 which was called: # once (10µs+14µs) by XML::SAX::Expat::BEGIN@10 at line 99
no warnings 'uninitialized';
# spent 23µs making 1 call to XML::NamespaceSupport::BEGIN@99 # spent 14µs making 1 call to warnings::unimport
10087µs if ($prefix eq 'xml' and $value ne $NS_XML) {
101 die "The xml prefix can only be bound to the $NS_XML namespace."
102 }
103 elsif ($value eq $NS_XML and $prefix ne 'xml') {
104 die "the $NS_XML namespace can only be bound to the xml prefix.";
105 }
106 elsif ($value eq $NS_XML and $prefix eq 'xml') {
107 return 1;
108 }
10989µs return 0 if index(lc($prefix), 'xml') == 0;
11021.04ms240µs
# spent 23µs (6+17) within XML::NamespaceSupport::BEGIN@110 which was called: # once (6µs+17µs) by XML::SAX::Expat::BEGIN@10 at line 110
use warnings 'uninitialized';
# spent 23µs making 1 call to XML::NamespaceSupport::BEGIN@110 # spent 17µs making 1 call to warnings::import
111
11285µs if (defined $prefix and $prefix eq '') {
113 $self->[NSMAP]->[-1]->[DEFAULT] = $value;
114 }
115 else {
11681µs die "Cannot undeclare prefix $prefix" if $value eq '' and not $self->[XMLNS_11];
11782µs if (not defined $prefix and $self->[AUTO_PREFIX]) {
118 while (1) {
119 $prefix = $self->[UNKNOWN_PREF]++;
120 last if not exists $self->[NSMAP]->[-1]->[PREFIX_MAP]->{$prefix};
121 }
122 }
123 elsif (not defined $prefix and not $self->[AUTO_PREFIX]) {
124 return 0;
125 }
12687µs $self->[NSMAP]->[-1]->[PREFIX_MAP]->{$prefix} = $value;
127 }
12885µs push @{$self->[NSMAP]->[-1]->[DECLARATIONS]}, $prefix;
129814µs return 1;
130}
131#-------------------------------------------------------------------#
132
133#-------------------------------------------------------------------#
134# declare_prefixes() - declare several prefixes in the current scope
135#-------------------------------------------------------------------#
136sub declare_prefixes {
137 my $self = shift;
138 my %prefixes = @_;
139 while (my ($k,$v) = each %prefixes) {
140 $self->declare_prefix($k,$v);
141 }
142}
143#-------------------------------------------------------------------#
144
145#-------------------------------------------------------------------#
146# undeclare_prefix
147#-------------------------------------------------------------------#
148sub undeclare_prefix {
149 my $self = shift;
150 my $prefix = shift;
151 return unless not defined $prefix or $prefix eq '';
152 return unless exists $self->[NSMAP]->[-1]->[PREFIX_MAP]->{$prefix};
153
154 my ( $tfix ) = grep { $_ eq $prefix } @{$self->[NSMAP]->[-1]->[DECLARATIONS]};
155 if ( not defined $tfix ) {
156 die "prefix $prefix not declared in this context\n";
157 }
158
159 @{$self->[NSMAP]->[-1]->[DECLARATIONS]} = grep { $_ ne $prefix } @{$self->[NSMAP]->[-1]->[DECLARATIONS]};
160 delete $self->[NSMAP]->[-1]->[PREFIX_MAP]->{$prefix};
161}
162#-------------------------------------------------------------------#
163
164#-------------------------------------------------------------------#
165# get_prefix() - get a (random) prefix for a given URI
166#-------------------------------------------------------------------#
167sub get_prefix {
168 my $self = shift;
169 my $uri = shift;
170
171 # we have to iterate over the whole hash here because if we don't
172 # the iterator isn't reset and the next pass will fail
173 my $pref;
174 while (my ($k, $v) = each %{$self->[NSMAP]->[-1]->[PREFIX_MAP]}) {
175 $pref = $k if $v eq $uri;
176 }
177 return $pref;
178}
179#-------------------------------------------------------------------#
180
181#-------------------------------------------------------------------#
182# get_prefixes() - get all the prefixes for a given URI
183#-------------------------------------------------------------------#
184sub get_prefixes {
185 my $self = shift;
186 my $uri = shift;
187
188 return keys %{$self->[NSMAP]->[-1]->[PREFIX_MAP]} unless defined $uri;
189 return grep { $self->[NSMAP]->[-1]->[PREFIX_MAP]->{$_} eq $uri } keys %{$self->[NSMAP]->[-1]->[PREFIX_MAP]};
190}
191#-------------------------------------------------------------------#
192
193#-------------------------------------------------------------------#
194# get_declared_prefixes() - get all prefixes declared in the last context
195#-------------------------------------------------------------------#
196sub get_declared_prefixes {
197 return @{$_[0]->[NSMAP]->[-1]->[DECLARATIONS]};
198}
199#-------------------------------------------------------------------#
200
201#-------------------------------------------------------------------#
202# get_uri() - get an URI given a prefix
203#-------------------------------------------------------------------#
204sub get_uri {
205 my $self = shift;
206 my $prefix = shift;
207
208 warn "Prefix must not be undef in get_uri(). The emtpy prefix must be ''" unless defined $prefix;
209
210 return $self->[NSMAP]->[-1]->[DEFAULT] if $prefix eq '';
211 return $self->[NSMAP]->[-1]->[PREFIX_MAP]->{$prefix} if exists $self->[NSMAP]->[-1]->[PREFIX_MAP]->{$prefix};
212 return undef;
213}
214#-------------------------------------------------------------------#
215
216#-------------------------------------------------------------------#
217# process_name() - provide details on a name
218#-------------------------------------------------------------------#
219sub process_name {
220 my $self = shift;
221 my $qname = shift;
222 my $aflag = shift;
223
224 if ($self->[FATALS]) {
225 return( ($self->_get_ns_details($qname, $aflag))[0,2], $qname );
226 }
227 else {
228 eval { return( ($self->_get_ns_details($qname, $aflag))[0,2], $qname ); }
229 }
230}
231#-------------------------------------------------------------------#
232
233#-------------------------------------------------------------------#
234# process_element_name() - provide details on a element's name
235#-------------------------------------------------------------------#
236
# spent 756µs (346+411) within XML::NamespaceSupport::process_element_name which was called 142 times, avg 5µs/call: # 142 times (346µs+411µs) by XML::SAX::Expat::_handle_start at line 215 of XML/SAX/Expat.pm, avg 5µs/call
sub process_element_name {
23714219µs my $self = shift;
23814217µs my $qname = shift;
239
240142246µs142411µs if ($self->[FATALS]) {
# spent 411µs making 142 calls to XML::NamespaceSupport::_get_ns_details, avg 3µs/call
241 return $self->_get_ns_details($qname, 0);
242 }
243 else {
244 eval { return $self->_get_ns_details($qname, 0); }
245 }
246}
247#-------------------------------------------------------------------#
248
249
250#-------------------------------------------------------------------#
251# process_attribute_name() - provide details on a attribute's name
252#-------------------------------------------------------------------#
253
# spent 322µs (145+177) within XML::NamespaceSupport::process_attribute_name which was called 56 times, avg 6µs/call: # 56 times (145µs+177µs) by XML::SAX::Expat::_handle_start at line 202 of XML/SAX/Expat.pm, avg 6µs/call
sub process_attribute_name {
254567µs my $self = shift;
2555610µs my $qname = shift;
256
25756100µs56177µs if ($self->[FATALS]) {
# spent 177µs making 56 calls to XML::NamespaceSupport::_get_ns_details, avg 3µs/call
258 return $self->_get_ns_details($qname, 1);
259 }
260 else {
261 eval { return $self->_get_ns_details($qname, 1); }
262 }
263}
264#-------------------------------------------------------------------#
265
266
267#-------------------------------------------------------------------#
268# ($ns, $prefix, $lname) = $self->_get_ns_details($qname, $f_attr)
269# returns ns, prefix, and lname for a given attribute name
270# >> the $f_attr flag, if set to one, will work for an attribute
271#-------------------------------------------------------------------#
272
# spent 588µs within XML::NamespaceSupport::_get_ns_details which was called 198 times, avg 3µs/call: # 142 times (411µs+0s) by XML::NamespaceSupport::process_element_name at line 240, avg 3µs/call # 56 times (177µs+0s) by XML::NamespaceSupport::process_attribute_name at line 257, avg 3µs/call
sub _get_ns_details {
27319820µs my $self = shift;
27419823µs my $qname = shift;
27519817µs my $aflag = shift;
276
27719812µs my ($ns, $prefix, $lname);
278198195µs (my ($tmp_prefix, $tmp_lname) = split /:/, $qname, 3)
279 < 3 or die "Invalid QName: $qname";
280
281 # no prefix
28219837µs my $cur_map = $self->[NSMAP]->[-1];
28319851µs if (not defined($tmp_lname)) {
28418218µs $prefix = undef;
28518221µs $lname = $qname;
286 # attr don't have a default namespace
28718233µs $ns = ($aflag) ? undef : $cur_map->[DEFAULT];
288 }
289
290 # prefix
291 else {
292167µs if (exists $cur_map->[PREFIX_MAP]->{$tmp_prefix}) {
293162µs $prefix = $tmp_prefix;
294162µs $lname = $tmp_lname;
295165µs $ns = $cur_map->[PREFIX_MAP]->{$prefix}
296 }
297 else { # no ns -> lname == name, all rest undef
298 die "Undeclared prefix: $tmp_prefix";
299 }
300 }
301
302198331µs return ($ns, $prefix, $lname);
303}
304#-------------------------------------------------------------------#
305
306#-------------------------------------------------------------------#
307# parse_jclark_notation() - parse the Clarkian notation
308#-------------------------------------------------------------------#
309sub parse_jclark_notation {
310 shift;
311 my $jc = shift;
312 $jc =~ m/^\{(.*)\}([^}]+)$/;
313 return $1, $2;
314}
315#-------------------------------------------------------------------#
316
317
318#-------------------------------------------------------------------#
319# Java names mapping
320#-------------------------------------------------------------------#
32111µs*XML::NamespaceSupport::pushContext = \&push_context;
3221300ns*XML::NamespaceSupport::popContext = \&pop_context;
3231100ns*XML::NamespaceSupport::declarePrefix = \&declare_prefix;
3241100ns*XML::NamespaceSupport::declarePrefixes = \&declare_prefixes;
3251200ns*XML::NamespaceSupport::getPrefix = \&get_prefix;
3261200ns*XML::NamespaceSupport::getPrefixes = \&get_prefixes;
3271200ns*XML::NamespaceSupport::getDeclaredPrefixes = \&get_declared_prefixes;
3281100ns*XML::NamespaceSupport::getURI = \&get_uri;
3291200ns*XML::NamespaceSupport::processName = \&process_name;
3301100ns*XML::NamespaceSupport::processElementName = \&process_element_name;
3311100ns*XML::NamespaceSupport::processAttributeName = \&process_attribute_name;
3321200ns*XML::NamespaceSupport::parseJClarkNotation = \&parse_jclark_notation;
3331100ns*XML::NamespaceSupport::undeclarePrefix = \&undeclare_prefix;
334#-------------------------------------------------------------------#
335
336
33716µs1;
338#,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,#
339#`,`, Documentation `,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,#
340#```````````````````````````````````````````````````````````````````#
341
342=pod
343
344=head1 NAME
345
346XML::NamespaceSupport - a simple generic namespace support class
347
348=head1 SYNOPSIS
349
350 use XML::NamespaceSupport;
351 my $nsup = XML::NamespaceSupport->new;
352
353 # add a new empty context
354 $nsup->push_context;
355 # declare a few prefixes
356 $nsup->declare_prefix($prefix1, $uri1);
357 $nsup->declare_prefix($prefix2, $uri2);
358 # the same shorter
359 $nsup->declare_prefixes($prefix1 => $uri1, $prefix2 => $uri2);
360
361 # get a single prefix for a URI (randomly)
362 $prefix = $nsup->get_prefix($uri);
363 # get all prefixes for a URI (probably better)
364 @prefixes = $nsup->get_prefixes($uri);
365 # get all prefixes in scope
366 @prefixes = $nsup->get_prefixes();
367 # get all prefixes that were declared for the current scope
368 @prefixes = $nsup->get_declared_prefixes;
369 # get a URI for a given prefix
370 $uri = $nsup->get_uri($prefix);
371
372 # get info on a qname (java-ish way, it's a bit weird)
373 ($ns_uri, $local_name, $qname) = $nsup->process_name($qname, $is_attr);
374 # the same, more perlish
375 ($ns_uri, $prefix, $local_name) = $nsup->process_element_name($qname);
376 ($ns_uri, $prefix, $local_name) = $nsup->process_attribute_name($qname);
377
378 # remove the current context
379 $nsup->pop_context;
380
381 # reset the object for reuse in another document
382 $nsup->reset;
383
384 # a simple helper to process Clarkian Notation
385 my ($ns, $lname) = $nsup->parse_jclark_notation('{http://foo}bar');
386 # or (given that it doesn't care about the object
387 my ($ns, $lname) = XML::NamespaceSupport->parse_jclark_notation('{http://foo}bar');
388
389
390=head1 DESCRIPTION
391
392This module offers a simple to process namespaced XML names (unames)
393from within any application that may need them. It also helps maintain
394a prefix to namespace URI map, and provides a number of basic checks.
395
396The model for this module is SAX2's NamespaceSupport class, readable at
397http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/helpers/NamespaceSupport.html.
398It adds a few perlisations where we thought it appropriate.
399
400=head1 METHODS
401
402=over 4
403
404=item * XML::NamespaceSupport->new(\%options)
405
406A simple constructor.
407
408The options are C<xmlns>, C<fatal_errors>, and C<auto_prefix>
409
410If C<xmlns> is turned on (it is off by default) the mapping from the
411xmlns prefix to the URI defined for it in DOM level 2 is added to the
412list of predefined mappings (which normally only contains the xml
413prefix mapping).
414
415If C<fatal_errors> is turned off (it is on by default) a number of
416validity errors will simply be flagged as failures, instead of
417die()ing.
418
419If C<auto_prefix> is turned on (it is off by default) when one
420provides a prefix of C<undef> to C<declare_prefix> it will generate a
421random prefix mapped to that namespace. Otherwise an undef prefix will
422trigger a warning (you should probably know what you're doing if you
423turn this option on).
424
425If C<xmlns_11> us turned off, it becomes illegal to undeclare namespace
426prefixes. It is on by default. This behaviour is compliant with Namespaces
427in XML 1.1, turning it off reverts you to version 1.0.
428
429=item * $nsup->push_context
430
431Adds a new empty context to the stack. You can then populate it with
432new prefixes defined at this level.
433
434=item * $nsup->pop_context
435
436Removes the topmost context in the stack and reverts to the previous
437one. It will die() if you try to pop more than you have pushed.
438
439=item * $nsup->declare_prefix($prefix, $uri)
440
441Declares a mapping of $prefix to $uri, at the current level.
442
443Note that with C<auto_prefix> turned on, if you declare a prefix
444mapping in which $prefix is undef(), you will get an automatic prefix
445selected for you. If it is off you will get a warning.
446
447This is useful when you deal with code that hasn't kept prefixes around
448and need to reserialize the nodes. It also means that if you want to
449set the default namespace (ie with an empty prefix) you must use the
450empty string instead of undef. This behaviour is consistent with the
451SAX 2.0 specification.
452
453=item * $nsup->declare_prefixes(%prefixes2uris)
454
455Declares a mapping of several prefixes to URIs, at the current level.
456
457=item * $nsup->get_prefix($uri)
458
459Returns a prefix given an URI. Note that as several prefixes may be
460mapped to the same URI, it returns an arbitrary one. It'll return
461undef on failure.
462
463=item * $nsup->get_prefixes($uri)
464
465Returns an array of prefixes given an URI. It'll return all the
466prefixes if the uri is undef.
467
468=item * $nsup->get_declared_prefixes
469
470Returns an array of all the prefixes that have been declared within
471this context, ie those that were declared on the last element, not
472those that were declared above and are simply in scope.
473
474=item * $nsup->get_uri($prefix)
475
476Returns a URI for a given prefix. Returns undef on failure.
477
478=item * $nsup->process_name($qname, $is_attr)
479
480Given a qualified name and a boolean indicating whether this is an
481attribute or another type of name (those are differently affected by
482default namespaces), it returns a namespace URI, local name, qualified
483name tuple. I know that that is a rather abnormal list to return, but
484it is so for compatibility with the Java spec. See below for more
485Perlish alternatives.
486
487If the prefix is not declared, or if the name is not valid, it'll
488either die or return undef depending on the current setting of
489C<fatal_errors>.
490
491=item * $nsup->undeclare_prefix($prefix);
492
493Removes a namespace prefix from the current context. This function may
494be used in SAX's end_prefix_mapping when there is fear that a namespace
495declaration might be available outside their scope (which shouldn't
496normally happen, but you never know ;). This may be needed in order to
497properly support Namespace 1.1.
498
499=item * $nsup->process_element_name($qname)
500
501Given a qualified name, it returns a namespace URI, prefix, and local
502name tuple. This method applies to element names.
503
504If the prefix is not declared, or if the name is not valid, it'll
505either die or return undef depending on the current setting of
506C<fatal_errors>.
507
508=item * $nsup->process_attribute_name($qname)
509
510Given a qualified name, it returns a namespace URI, prefix, and local
511name tuple. This method applies to attribute names.
512
513If the prefix is not declared, or if the name is not valid, it'll
514either die or return undef depending on the current setting of
515C<fatal_errors>.
516
517=item * $nsup->reset
518
519Resets the object so that it can be reused on another document.
520
521=back
522
523All methods of the interface have an alias that is the name used in
524the original Java specification. You can use either name
525interchangeably. Here is the mapping:
526
527 Java name Perl name
528 ---------------------------------------------------
529 pushContext push_context
530 popContext pop_context
531 declarePrefix declare_prefix
532 declarePrefixes declare_prefixes
533 getPrefix get_prefix
534 getPrefixes get_prefixes
535 getDeclaredPrefixes get_declared_prefixes
536 getURI get_uri
537 processName process_name
538 processElementName process_element_name
539 processAttributeName process_attribute_name
540 parseJClarkNotation parse_jclark_notation
541 undeclarePrefix undeclare_prefix
542
543=head1 VARIABLES
544
545Two global variables are made available to you. They used to be constants but
546simple scalars are easier to use in a number of contexts. They are not
547exported but can easily be accessed from any package, or copied into it.
548
549=over 4
550
551=item * C<$NS_XMLNS>
552
553The namespace for xmlns prefixes, http://www.w3.org/2000/xmlns/.
554
555=item * C<$NS_XML>
556
557The namespace for xml prefixes, http://www.w3.org/XML/1998/namespace.
558
559=back
560
561=head1 TODO
562
563 - add more tests
564 - optimise here and there
565
566=head1 AUTHOR
567
568Robin Berjon, robin@knowscape.com, with lots of it having been done
569by Duncan Cameron, and a number of suggestions from the perl-xml
570list.
571
572=head1 COPYRIGHT
573
574Copyright (c) 2001-2005 Robin Berjon. All rights reserved. This program is
575free software; you can redistribute it and/or modify it under the same terms
576as Perl itself.
577
578=head1 SEE ALSO
579
580XML::Parser::PerlSAX
581
582=cut
583
Report produced by the NYTProf 5.06 Perl profiler, developed by Tim Bunce and Adam Kaplan.