XML::NamespaceSupport(3pm)

1XML::NamespaceSupport(3U)ser Contributed Perl DocumentatiXoMnL::NamespaceSupport(3)
2
3
4

NAME

6       XML::NamespaceSupport - a simple generic namespace support class
7

SYNOPSIS

9         use XML::NamespaceSupport;
10         my $nsup = XML::NamespaceSupport->new;
11
12         # 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
20         # 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
31         # 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
37         # remove the current context
38         $nsup->pop_context;
39
40         # reset the object for reuse in another document
41         $nsup->reset;
42
43         # 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

DESCRIPTION

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
53       The model for this module is SAX2's NamespaceSupport class, readable at
54       http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/helpers/NamespaceSupport.html.
55       It adds a few perlisations where we thought it appropriate.
56

METHODS

58       ·   XML::NamespaceSupport->new(\%options)
59
60           A simple constructor.
61
62           The options are "xmlns", "fatal_errors", and "auto_prefix"
63
64           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
69           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
73           If "auto_prefix" is turned on (it is off by default) when one
74           provides 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
79           If "xmlns_11" us turned off, it becomes illegal to undeclare
80           namespace prefixes. It is on by default. This behaviour is
81           compliant with Namespaces in XML 1.1, turning it off reverts you to
82           version 1.0.
83
84       ·   $nsup->push_context
85
86           Adds a new empty context to the stack. You can then populate it
87           with new prefixes defined at this level.
88
89       ·   $nsup->pop_context
90
91           Removes the topmost context in the stack and reverts to the
92           previous one. It will die() if you try to pop more than you have
93           pushed.
94
95       ·   $nsup->declare_prefix($prefix, $uri)
96
97           Declares a mapping of $prefix to $uri, at the current level.
98
99           Note that with "auto_prefix" turned on, if you declare a prefix
100           mapping in which $prefix is undef(), you will get an automatic
101           prefix selected for you. If it is off you will get a warning.
102
103           This is useful when you deal with code that hasn't kept prefixes
104           around and need to reserialize the nodes. It also means that if you
105           want to set the default namespace (ie with an empty prefix) you
106           must use the empty string instead of undef. This behaviour is
107           consistent with the SAX 2.0 specification.
108
109       ·   $nsup->declare_prefixes(%prefixes2uris)
110
111           Declares a mapping of several prefixes to URIs, at the current
112           level.
113
114       ·   $nsup->get_prefix($uri)
115
116           Returns a prefix given an URI. Note that as several prefixes may be
117           mapped to the same URI, it returns an arbitrary one. It'll return
118           undef on failure.
119
120       ·   $nsup->get_prefixes($uri)
121
122           Returns an array of prefixes given an URI. It'll return all the
123           prefixes if the uri is undef.
124
125       ·   $nsup->get_declared_prefixes
126
127           Returns an array of all the prefixes that have been declared within
128           this context, ie those that were declared on the last element, not
129           those that were declared above and are simply in scope.
130
131       ·   $nsup->get_uri($prefix)
132
133           Returns a URI for a given prefix. Returns undef on failure.
134
135       ·   $nsup->process_name($qname, $is_attr)
136
137           Given a qualified name and a boolean indicating whether this is an
138           attribute or another type of name (those are differently affected
139           by default namespaces), it returns a namespace URI, local name,
140           qualified name tuple. I know that that is a rather abnormal list to
141           return, but it is so for compatibility with the Java spec. See
142           below for more Perlish alternatives.
143
144           If the prefix is not declared, or if the name is not valid, it'll
145           either die or return undef depending on the current setting of
146           "fatal_errors".
147
148       ·   $nsup->undeclare_prefix($prefix);
149
150           Removes a namespace prefix from the current context. This function
151           may be used in SAX's end_prefix_mapping when there is fear that a
152           namespace declaration might be available outside their scope (which
153           shouldn't normally happen, but you never know ;). This may be
154           needed in order to properly support Namespace 1.1.
155
156       ·   $nsup->process_element_name($qname)
157
158           Given a qualified name, it returns a namespace URI, prefix, and
159           local name tuple. This method applies to element names.
160
161           If the prefix is not declared, or if the name is not valid, it'll
162           either die or return undef depending on the current setting of
163           "fatal_errors".
164
165       ·   $nsup->process_attribute_name($qname)
166
167           Given a qualified name, it returns a namespace URI, prefix, and
168           local name tuple. This method applies to attribute names.
169
170           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
174       ·   $nsup->reset
175
176           Resets the object so that it can be reused on another document.
177
178       All methods of the interface have an alias that is the name used in the
179       original Java specification. You can use either name interchangeably.
180       Here is the mapping:
181
182         Java name                 Perl name
183         ---------------------------------------------------
184         pushContext               push_context
185         popContext                pop_context
186         declarePrefix             declare_prefix
187         declarePrefixes           declare_prefixes
188         getPrefix                 get_prefix
189         getPrefixes               get_prefixes
190         getDeclaredPrefixes       get_declared_prefixes
191         getURI                    get_uri
192         processName               process_name
193         processElementName        process_element_name
194         processAttributeName      process_attribute_name
195         parseJClarkNotation       parse_jclark_notation
196         undeclarePrefix           undeclare_prefix
197

VARIABLES

199       Two global variables are made available to you. They used to be
200       constants but simple scalars are easier to use in a number of contexts.
201       They are not exported but can easily be accessed from any package, or
202       copied into it.
203
204       ·   $NS_XMLNS
205
206           The namespace for xmlns prefixes, http://www.w3.org/2000/xmlns/.
207
208       ·   $NS_XML
209
210           The namespace for xml prefixes,
211           http://www.w3.org/XML/1998/namespace.
212

TODO

214        - add more tests
215        - optimise here and there
216

AUTHOR

218       Robin Berjon, robin@knowscape.com, with lots of it having been done by
219       Duncan Cameron, and a number of suggestions from the perl-xml list.
220

COPYRIGHT

222       Copyright (c) 2001-2005 Robin Berjon. All rights reserved. This program
223       is free software; you can redistribute it and/or modify it under the
224       same terms as Perl itself.
225