1NamespaceSupport(3) User Contributed Perl Documentation NamespaceSupport(3)
2
6 XML::NamespaceSupport - a simple generic namespace support class
7
9 use XML::NamespaceSupport;
10 my $nsup = XML::NamespaceSupport->new;
11 # add a new empty context
13 $nsup->push_context;
14 # declare a few prefixes
15 $nsup->declare_prefix($prefix1, $uri1);
16 $nsup->declare_prefix($prefix2, $uri2);
17 # the same shorter
18 $nsup->declare_prefixes($prefix1 => $uri1, $prefix2 => $uri2);
19 # get a single prefix for a URI (randomly)
21 $prefix = $nsup->get_prefix($uri);
22 # get all prefixes for a URI (probably better)
23 @prefixes = $nsup->get_prefixes($uri);
24 # get all prefixes in scope
25 @prefixes = $nsup->get_prefixes();
26 # get all prefixes that were declared for the current scope
27 @prefixes = $nsup->get_declared_prefixes;
28 # get a URI for a given prefix
29 $uri = $nsup->get_uri($prefix);
30 # get info on a qname (java-ish way, it's a bit weird)
32 ($ns_uri, $local_name, $qname) = $nsup->process_name($qname, $is_attr);
33 # the same, more perlish
34 ($ns_uri, $prefix, $local_name) = $nsup->process_element_name($qname);
35 ($ns_uri, $prefix, $local_name) = $nsup->process_attribute_name($qname);
36 # remove the current context
38 $nsup->pop_context;
39 # reset the object for reuse in another document
41 $nsup->reset;
42 # a simple helper to process Clarkian Notation
44 my ($ns, $lname) = $nsup->parse_jclark_notation('{http://foo}bar');
45 # or (given that it doesn't care about the object
46 my ($ns, $lname) = XML::NamespaceSupport->parse_jclark_notation('{http://foo}bar');
47
49 This module offers a simple to process namespaced XML names (unames)
50 from within any application that may need them. It also helps maintain
51 a prefix to namespace URI map, and provides a number of basic checks.
52 The model for this module is SAX2's NamespaceSupport class, readable at
54 http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/helpers/Names‐
55 paceSupport.html. It adds a few perlisations where we thought it
56 appropriate.
57
59 * XML::NamespaceSupport->new(\%options)
60 A simple constructor.
61 The options are "xmlns", "fatal_errors", and "auto_prefix"
63 If "xmlns" is turned on (it is off by default) the mapping from the
65 xmlns prefix to the URI defined for it in DOM level 2 is added to
66 the list of predefined mappings (which normally only contains the
67 xml prefix mapping).
68 If "fatal_errors" is turned off (it is on by default) a number of
70 validity errors will simply be flagged as failures, instead of
71 die()ing.
72 If "auto_prefix" is turned on (it is off by default) when one pro‐
74 vides a prefix of "undef" to "declare_prefix" it will generate a
75 random prefix mapped to that namespace. Otherwise an undef prefix
76 will trigger a warning (you should probably know what you're doing
77 if you turn this option on).
78 If "xmlns_11" us turned off, it becomes illegal to undeclare names‐
80 pace prefixes. It is on by default. This behaviour is compliant
81 with Namespaces in XML 1.1, turning it off reverts you to version
82 1.0.
83 * $nsup->push_context
85 Adds a new empty context to the stack. You can then populate it
86 with new prefixes defined at this level.
87 * $nsup->pop_context
89 Removes the topmost context in the stack and reverts to the previ‐
90 ous one. It will die() if you try to pop more than you have pushed.
91 * $nsup->declare_prefix($prefix, $uri)
93 Declares a mapping of $prefix to $uri, at the current level.
94 Note that with "auto_prefix" turned on, if you declare a prefix
96 mapping in which $prefix is undef(), you will get an automatic pre‐
97 fix selected for you. If it is off you will get a warning.
98 This is useful when you deal with code that hasn't kept prefixes
100 around and need to reserialize the nodes. It also means that if you
101 want to set the default namespace (ie with an empty prefix) you
102 must use the empty string instead of undef. This behaviour is con‐
103 sistent with the SAX 2.0 specification.
104 * $nsup->declare_prefixes(%prefixes2uris)
106 Declares a mapping of several prefixes to URIs, at the current
107 level.
108 * $nsup->get_prefix($uri)
110 Returns a prefix given an URI. Note that as several prefixes may be
111 mapped to the same URI, it returns an arbitrary one. It'll return
112 undef on failure.
113 * $nsup->get_prefixes($uri)
115 Returns an array of prefixes given an URI. It'll return all the
116 prefixes if the uri is undef.
117 * $nsup->get_declared_prefixes
119 Returns an array of all the prefixes that have been declared within
120 this context, ie those that were declared on the last element, not
121 those that were declared above and are simply in scope.
122 * $nsup->get_uri($prefix)
124 Returns a URI for a given prefix. Returns undef on failure.
125 * $nsup->process_name($qname, $is_attr)
127 Given a qualified name and a boolean indicating whether this is an
128 attribute or another type of name (those are differently affected
129 by default namespaces), it returns a namespace URI, local name,
130 qualified name tuple. I know that that is a rather abnormal list to
131 return, but it is so for compatibility with the Java spec. See
132 below for more Perlish alternatives.
133 If the prefix is not declared, or if the name is not valid, it'll
135 either die or return undef depending on the current setting of
136 "fatal_errors".
137 * $nsup->undeclare_prefix($prefix);
139 Removes a namespace prefix from the current context. This function
140 may be used in SAX's end_prefix_mapping when there is fear that a
141 namespace declaration might be available outside their scope (which
142 shouldn't normally happen, but you never know ;). This may be
143 needed in order to properly support Namespace 1.1.
144 * $nsup->process_element_name($qname)
146 Given a qualified name, it returns a namespace URI, prefix, and
147 local name tuple. This method applies to element names.
148 If the prefix is not declared, or if the name is not valid, it'll
150 either die or return undef depending on the current setting of
151 "fatal_errors".
152 * $nsup->process_attribute_name($qname)
154 Given a qualified name, it returns a namespace URI, prefix, and
155 local name tuple. This method applies to attribute names.
156 If the prefix is not declared, or if the name is not valid, it'll
158 either die or return undef depending on the current setting of
159 "fatal_errors".
160 * $nsup->reset
162 Resets the object so that it can be reused on another document.
163 All methods of the interface have an alias that is the name used in the
165 original Java specification. You can use either name interchangeably.
166 Here is the mapping:
167 Java name Perl name
169 ---------------------------------------------------
170 pushContext push_context
171 popContext pop_context
172 declarePrefix declare_prefix
173 declarePrefixes declare_prefixes
174 getPrefix get_prefix
175 getPrefixes get_prefixes
176 getDeclaredPrefixes get_declared_prefixes
177 getURI get_uri
178 processName process_name
179 processElementName process_element_name
180 processAttributeName process_attribute_name
181 parseJClarkNotation parse_jclark_notation
182 undeclarePrefix undeclare_prefix
183
185 Two global variables are made available to you. They used to be con‐
186 stants but simple scalars are easier to use in a number of contexts.
187 They are not exported but can easily be accessed from any package, or
188 copied into it.
189 * $NS_XMLNS
191 The namespace for xmlns prefixes, http://www.w3.org/2000/xmlns/.
192 * $NS_XML
194 The namespace for xml prefixes, http://www.w3.org/XML/1998/names‐
195 pace.
196
198 - add more tests
199 - optimise here and there
200
202 Robin Berjon, robin@knowscape.com, with lots of it having been done by
203 Duncan Cameron, and a number of suggestions from the perl-xml list.
204
206 Copyright (c) 2001-2005 Robin Berjon. All rights reserved. This program
207 is free software; you can redistribute it and/or modify it under the
208 same terms as Perl itself.
209
211 XML::Parser::PerlSAX
212perl v5.8.8 2005-05-12 NamespaceSupport(3)