1XML::NamespaceSupport(3U)ser Contributed Perl DocumentatiXoMnL::NamespaceSupport(3)
2
6 XML::NamespaceSupport - A simple generic namespace processor
7
9 version 1.12
10
12 use XML::NamespaceSupport;
13 my $nsup = XML::NamespaceSupport->new;
14 # add a new empty context
16 $nsup->push_context;
17 # declare a few prefixes
18 $nsup->declare_prefix($prefix1, $uri1);
19 $nsup->declare_prefix($prefix2, $uri2);
20 # the same shorter
21 $nsup->declare_prefixes($prefix1 => $uri1, $prefix2 => $uri2);
22 # get a single prefix for a URI (randomly)
24 $prefix = $nsup->get_prefix($uri);
25 # get all prefixes for a URI (probably better)
26 @prefixes = $nsup->get_prefixes($uri);
27 # get all prefixes in scope
28 @prefixes = $nsup->get_prefixes();
29 # get all prefixes that were declared for the current scope
30 @prefixes = $nsup->get_declared_prefixes;
31 # get a URI for a given prefix
32 $uri = $nsup->get_uri($prefix);
33 # get info on a qname (java-ish way, it's a bit weird)
35 ($ns_uri, $local_name, $qname) = $nsup->process_name($qname, $is_attr);
36 # the same, more perlish
37 ($ns_uri, $prefix, $local_name) = $nsup->process_element_name($qname);
38 ($ns_uri, $prefix, $local_name) = $nsup->process_attribute_name($qname);
39 # remove the current context
41 $nsup->pop_context;
42 # reset the object for reuse in another document
44 $nsup->reset;
45 # a simple helper to process Clarkian Notation
47 my ($ns, $lname) = $nsup->parse_jclark_notation('{http://foo}bar');
48 # or (given that it doesn't care about the object
49 my ($ns, $lname) = XML::NamespaceSupport->parse_jclark_notation('{http://foo}bar');
50
52 This module offers a simple to process namespaced XML names (unames)
53 from within any application that may need them. It also helps maintain
54 a prefix to namespace URI map, and provides a number of basic checks.
55 The model for this module is SAX2's NamespaceSupport class, readable at
57 http://www.saxproject.org/namespaces.html It adds a few perlisations
58 where we thought it appropriate.
59
61 XML::NamespaceSupport - a simple generic namespace support class
62
64 • XML::NamespaceSupport->new(\%options)
65 A simple constructor.
67 The options are "xmlns", "fatal_errors", and "auto_prefix"
69 If "xmlns" is turned on (it is off by default) the mapping from the
71 xmlns prefix to the URI defined for it in DOM level 2 is added to
72 the list of predefined mappings (which normally only contains the
73 xml prefix mapping).
74 If "fatal_errors" is turned off (it is on by default) a number of
76 validity errors will simply be flagged as failures, instead of
77 die()ing.
78 If "auto_prefix" is turned on (it is off by default) when one
80 provides a prefix of "undef" to "declare_prefix" it will generate a
81 random prefix mapped to that namespace. Otherwise an undef prefix
82 will trigger a warning (you should probably know what you're doing
83 if you turn this option on).
84 If "xmlns_11" us turned off, it becomes illegal to undeclare
86 namespace prefixes. It is on by default. This behaviour is
87 compliant with Namespaces in XML 1.1, turning it off reverts you to
88 version 1.0.
89 • $nsup->push_context
91 Adds a new empty context to the stack. You can then populate it
93 with new prefixes defined at this level.
94 • $nsup->pop_context
96 Removes the topmost context in the stack and reverts to the
98 previous one. It will die() if you try to pop more than you have
99 pushed.
100 • $nsup->declare_prefix($prefix, $uri)
102 Declares a mapping of $prefix to $uri, at the current level.
104 Note that with "auto_prefix" turned on, if you declare a prefix
106 mapping in which $prefix is undef(), you will get an automatic
107 prefix selected for you. If it is off you will get a warning.
108 This is useful when you deal with code that hasn't kept prefixes
110 around and need to reserialize the nodes. It also means that if you
111 want to set the default namespace (i.e. with an empty prefix) you
112 must use the empty string instead of undef. This behaviour is
113 consistent with the SAX 2.0 specification.
114 • $nsup->declare_prefixes(%prefixes2uris)
116 Declares a mapping of several prefixes to URIs, at the current
118 level.
119 • $nsup->get_prefix($uri)
121 Returns a prefix given a URI. Note that as several prefixes may be
123 mapped to the same URI, it returns an arbitrary one. It'll return
124 undef on failure.
125 • $nsup->get_prefixes($uri)
127 Returns an array of prefixes given a URI. It'll return all the
129 prefixes if the uri is undef.
130 • $nsup->get_declared_prefixes
132 Returns an array of all the prefixes that have been declared within
134 this context, ie those that were declared on the last element, not
135 those that were declared above and are simply in scope.
136 Note that at least one context must be added to the stack via
138 "push_context" before this method can be called.
139 • $nsup->get_uri($prefix)
141 Returns a URI for a given prefix. Returns undef on failure.
143 • $nsup->process_name($qname, $is_attr)
145 Given a qualified name and a boolean indicating whether this is an
147 attribute or another type of name (those are differently affected
148 by default namespaces), it returns a namespace URI, local name,
149 qualified name tuple. I know that that is a rather abnormal list to
150 return, but it is so for compatibility with the Java spec. See
151 below for more Perlish alternatives.
152 If the prefix is not declared, or if the name is not valid, it'll
154 either die or return undef depending on the current setting of
155 "fatal_errors".
156 • $nsup->undeclare_prefix($prefix);
158 Removes a namespace prefix from the current context. This function
160 may be used in SAX's end_prefix_mapping when there is fear that a
161 namespace declaration might be available outside their scope (which
162 shouldn't normally happen, but you never know ;) ). This may be
163 needed in order to properly support Namespace 1.1.
164 • $nsup->process_element_name($qname)
166 Given a qualified name, it returns a namespace URI, prefix, and
168 local name tuple. This method applies to element names.
169 If the prefix is not declared, or if the name is not valid, it'll
171 either die or return undef depending on the current setting of
172 "fatal_errors".
173 • $nsup->process_attribute_name($qname)
175 Given a qualified name, it returns a namespace URI, prefix, and
177 local name tuple. This method applies to attribute names.
178 If the prefix is not declared, or if the name is not valid, it'll
180 either die or return undef depending on the current setting of
181 "fatal_errors".
182 • $nsup->reset
184 Resets the object so that it can be reused on another document.
186 All methods of the interface have an alias that is the name used in the
188 original Java specification. You can use either name interchangeably.
189 Here is the mapping:
190 Java name Perl name
192 ---------------------------------------------------
193 pushContext push_context
194 popContext pop_context
195 declarePrefix declare_prefix
196 declarePrefixes declare_prefixes
197 getPrefix get_prefix
198 getPrefixes get_prefixes
199 getDeclaredPrefixes get_declared_prefixes
200 getURI get_uri
201 processName process_name
202 processElementName process_element_name
203 processAttributeName process_attribute_name
204 parseJClarkNotation parse_jclark_notation
205 undeclarePrefix undeclare_prefix
206
208 Two global variables are made available to you. They used to be
209 constants but simple scalars are easier to use in a number of contexts.
210 They are not exported but can easily be accessed from any package, or
211 copied into it.
212 • $NS_XMLNS
214 The namespace for xmlns prefixes, http://www.w3.org/2000/xmlns/.
216 • $NS_XML
218 The namespace for xml prefixes,
220 http://www.w3.org/XML/1998/namespace.
221
223 - add more tests
224 - optimise here and there
225
227 XML::Parser::PerlSAX
228
230 • Robin Berjon <robin@knowscape.com>
231 • Chris Prather <chris@prather.org>
233
235 This software is copyright (c) 2015 by Robin Berjon.
236 This is free software; you can redistribute it and/or modify it under
238 the same terms as the Perl 5 programming language system itself.
239
241 • Chris Prather <cprather@hdpublishing.com>
242 • David Steinbrunner <dsteinbrunner@pobox.com>
244 • Paul Cochrane <paul@liekut.de>
246 • Paulo Custodio <pauloscustodio@gmail.com>
248perl v5.36.0 2023-01-20 XML::NamespaceSupport(3)