XML::Namespace(3pm)

1XML::Namespace(3)     User Contributed Perl Documentation    XML::Namespace(3)
2
3
4

NAME

6       XML::Namespace - Simple support for XML Namespaces
7

SYNOPSIS

9        Example 1: using XML::Namespace objects
10
11           use XML::Namespace;
12
13           my $xsd = XML::Namespace->new('http://www.w3.org/2001/XMLSchema#');
14
15           # explicit access via the uri() method
16           print $xsd->uri();           # http://www.w3.org/2001/XMLSchema#
17           print $xsd->uri('integer');  # http://www.w3.org/2001/XMLSchema#integer
18
19           # implicit access through AUTOLOAD method
20           print $xsd->integer;         # http://www.w3.org/2001/XMLSchema#integer
21
22        Example 2: importing XML::Namespace objects
23
24           use XML::Namespace
25               xsd => 'http://www.w3.org/2001/XMLSchema#',
26               rdf => 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
27
28           # xsd and rdf are imported subroutines that return
29           # XML::Namespace objects which can be used as above
30
31           print xsd->uri('integer');   # http://www.w3.org/2001/XMLSchema#integer
32           print xsd->integer;          # http://www.w3.org/2001/XMLSchema#integer
33

DESCRIPTION

35       This module implements a simple object for representing XML Namespaces
36       in Perl.  It provides little more than some syntactic sugar for your
37       Perl programs, saving you the bother of typing lots of long-winded
38       URIs.  It was inspired by the Class::RDF::NS module distributed as part
39       of Class::RDF.
40
41   Using XML::Namespace Objects
42       First load the XML::Namespace module.
43
44           use XML::Namespace;
45
46       Then create an XML::Namespace object.
47
48           my $xsd = XML::Namespace->new('http://www.w3.org/2001/XMLSchema#');
49
50       Then use the uri() method to return an absolute URI from a relative
51       path.
52
53           print $xsd->uri('integer'); # http://www.w3.org/2001/XMLSchema#integer
54
55       Alternately, use the AUTOLOAD method to map method calls to the uri()
56       method.
57
58           print $xsd->integer;        # http://www.w3.org/2001/XMLSchema#integer
59
60   Importing XML::Namespace Objects
61       When you "use" the XML::Namespace module, you can specify a list of
62       namespace definitions.
63
64           use XML::Namespace
65               xsd => 'http://www.w3.org/2001/XMLSchema#',
66               rdf => 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
67
68       This defines the "xsd" and "rdf" subroutines and exports them into the
69       calling package.  The subroutines simply return XML::Namespace objects
70       initialised with the relevant namespace URIs.
71
72           print xsd->uri('integer');  # http://www.w3.org/2001/XMLSchema#integer
73           print xsd->integer;         # http://www.w3.org/2001/XMLSchema#integer
74
75   Overloaded Stringification Method
76       The XML::Namespace module overloads the stringification operator to
77       return the namespace URI.
78
79           my $xsd = XML::Namespace->new('http://www.w3.org/2001/XMLSchema#');
80
81           print $xsd;           # http://www.w3.org/2001/XMLSchema#
82

METHODS

84   new($uri)
85       Constructor method which creates a new XML::Namespace object.  It
86       expects a single argument denoting the URI that the namespace is to
87       represent.
88
89           use XML::Namespace;
90
91           my $xsd = XML::Namespace->new('http://www.w3.org/2001/XMLSchema#');
92
93   uri($path)
94       When called without arguments, this method returns the URI of the
95       namespace object, as defined by the argument passed to the new()
96       constructor method.
97
98           $xsd->uri();          # http://www.w3.org/2001/XMLSchema#
99
100       An argument can be passed to indicate a path relative to the namespace
101       URI.  The method returns a simple concatenation of the namespace URI
102       and the relative path argument.
103
104           $xsd->uri('integer'); # http://www.w3.org/2001/XMLSchema#integer
105
106   import($name,$uri,$name,$uri,...)
107       This method is provided to work with the Exporter mechanism.  It
108       expects a list of "($name, $uri)" pairs as arguments.  It creates
109       XML::Namespace objects and accessor subroutines that are then exported
110       to the caller's package.
111
112       Although not intended for manual invocation, there's nothing to stop
113       you from doing it.
114
115           use XML::Namespace;
116
117           XML::Namespace->import( xsd => 'http://www.w3.org/2001/XMLSchema#' );
118
119           xsd()->integer;   # http://www.w3.org/2001/XMLSchema#integer
120
121       Note that the parentheses are required when accessing this subroutine.
122
123           xsd()->integer;     # Good
124           xsd->integer;       # Bad
125
126       Unlike those that are defined automatically by the Importer, Perl
127       doesn't know anything about these subroutines at compile time.  Without
128       the parentheses, Perl will think you're trying to call the "integer"
129       method on an unknown "xsd" package and you'll see an error like:
130
131           Can't locate object method "integer" via package "xsd"
132
133       That's why it's better to define your namespaces when you load the
134       XML::Namespace module.
135
136           use XML::Namespace
137               xsd => 'http://www.w3.org/2001/XMLSchema#';
138
139           xsd->integer;       # Good
140
141   AUTOLOAD
142       The module defines an AUTOLOAD method that maps all other method calls
143       to the uri() method.  Thus, the following return the same value.
144
145           $xsd->uri('integer'); # http://www.w3.org/2001/XMLSchema#integer
146           $xsd->integer;        # http://www.w3.org/2001/XMLSchema#integer
147

AUTHOR

149       Andy Wardley <mailto:abw@cpan.org>
150

VERSION

152       This is version 0.02 of XML::Namespace.
153

COPYRIGHT

155       Copyright (C) 2005 Andy Wardley.  All Rights Reserved.
156
157       This module is free software; you can redistribute it and/or modify it
158       under the same terms as Perl itself.
159