← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 01.HTTP.t
  Run on Tue May 4 15:25:55 2010
Reported on Tue May 4 15:26:04 2010

File /usr/local/lib/perl5/site_perl/5.10.1/URI.pm
Statements Executed 224
Statement Execution Time 14.6ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
4113.28ms3.51msURI::::implementorURI::implementor
111882µs976µsURI::::BEGIN@22URI::BEGIN@22
411131µs2.37msURI::::_initURI::_init
422130µs6.06msURI::::newURI::new
92175µs123µsURI::::_schemeURI::_scheme
55274µs74µsURI::::CORE:regcompURI::CORE:regcomp (opcode)
276263µs63µsURI::::CORE:matchURI::CORE:match (opcode)
31153µs107µsURI::::canonicalURI::canonical
62141µs116µsURI::::schemeURI::scheme
41127µs39µsURI::::_uric_escapeURI::_uric_escape
238226µs26µsURI::::CORE:substURI::CORE:subst (opcode)
11116µs67µsURI::::BEGIN@24URI::BEGIN@24
11114µs17µsURI::::BEGIN@3URI::BEGIN@3
31112µs12µsURI::::as_stringURI::as_string
3119µs9µsURI::::__ANON__[:24]URI::__ANON__[:24]
1119µs27µsURI::::BEGIN@127URI::BEGIN@127
1116µs23µsURI::::BEGIN@4URI::BEGIN@4
1116µs39µsURI::::BEGIN@7URI::BEGIN@7
1116µs55µsURI::::BEGIN@13URI::BEGIN@13
1113µs3µsURI::::BEGIN@21URI::BEGIN@21
1113µs3µsURI::::_init_implementorURI::_init_implementor
0000s0sURI::::STORABLE_freezeURI::STORABLE_freeze
0000s0sURI::::STORABLE_thawURI::STORABLE_thaw
0000s0sURI::::__ANON__[:25]URI::__ANON__[:25]
0000s0sURI::::__ANON__[:26]URI::__ANON__[:26]
0000s0sURI::::_no_scheme_okURI::_no_scheme_ok
0000s0sURI::::_obj_eqURI::_obj_eq
0000s0sURI::::absURI::abs
0000s0sURI::::as_iriURI::as_iri
0000s0sURI::::cloneURI::clone
0000s0sURI::::eqURI::eq
0000s0sURI::::fragmentURI::fragment
0000s0sURI::::new_absURI::new_abs
0000s0sURI::::opaqueURI::opaque
0000s0sURI::::relURI::rel
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments
Time
on line
Calls Time
in subs
Code
1package URI;
2
3324µs220µs
# spent 17µs (14+3) within URI::BEGIN@3 which was called # once (14µs+3µs) by LWP::UserAgent::BEGIN@10 at line 3
use strict;
# spent 17µs making 1 call to URI::BEGIN@3 # spent 3µs making 1 call to strict::import
4328µs241µs
# spent 23µs (6+17) within URI::BEGIN@4 which was called # once (6µs+17µs) by LWP::UserAgent::BEGIN@10 at line 4
use vars qw($VERSION);
# spent 23µs making 1 call to URI::BEGIN@4 # spent 17µs making 1 call to vars::import
511µs$VERSION = "1.51";
6
7327µs273µs
# spent 39µs (6+33) within URI::BEGIN@7 which was called # once (6µs+33µs) by LWP::UserAgent::BEGIN@10 at line 7
use vars qw($ABS_REMOTE_LEADING_DOTS $ABS_ALLOW_RELATIVE_SCHEME $DEFAULT_QUERY_FORM_DELIMITER);
# spent 39µs making 1 call to URI::BEGIN@7 # spent 33µs making 1 call to vars::import
8
91200nsmy %implements; # mapping from scheme to implementor class
10
11# Some "official" character classes
12
13349µs2104µs
# spent 55µs (6+49) within URI::BEGIN@13 which was called # once (6µs+49µs) by LWP::UserAgent::BEGIN@10 at line 13
use vars qw($reserved $mark $unreserved $uric $scheme_re);
# spent 55µs making 1 call to URI::BEGIN@13 # spent 49µs making 1 call to vars::import
141400ns$reserved = q(;/?:@&=+$,[]);
151500ns$mark = q(-_.!~*'()); #'; emacs
1613µs$unreserved = "A-Za-z0-9\Q$mark\E";
1712µs$uric = quotemeta($reserved) . $unreserved . "%";
18
191300ns$scheme_re = '[a-zA-Z][a-zA-Z0-9.+\-]*';
20
21317µs13µs
# spent 3µs within URI::BEGIN@21 which was called # once (3µs+0s) by LWP::UserAgent::BEGIN@10 at line 21
use Carp ();
# spent 3µs making 1 call to URI::BEGIN@21
223182µs1976µs
# spent 976µs (882+94) within URI::BEGIN@22 which was called # once (882µs+94µs) by LWP::UserAgent::BEGIN@10 at line 22
use URI::Escape ();
# spent 976µs making 1 call to URI::BEGIN@22
23
24313µs
# spent 67µs (16+51) within URI::BEGIN@24 which was called # once (16µs+51µs) by LWP::UserAgent::BEGIN@10 at line 28 # spent 9µs within URI::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/URI.pm:24] which was called 3 times, avg 3µs/call: # 3 times (9µs+0s) by LWP::UserAgent::prepare_request at line 210 of LWP/UserAgent.pm, avg 3µs/call
use overload ('""' => sub { ${$_[0]} },
25 '==' => sub { _obj_eq(@_) },
26 '!=' => sub { !_obj_eq(@_) },
27 fallback => 1,
# spent 51µs making 1 call to overload::import
283420µs167µs );
# spent 67µs making 1 call to URI::BEGIN@24
29
30# Check if two objects are the same object
31sub _obj_eq {
32 return overload::StrVal($_[0]) eq overload::StrVal($_[1]);
33}
34
35sub new
36
# spent 6.06ms (130µs+5.93) within URI::new which was called 4 times, avg 1.52ms/call: # 3 times (80µs+431µs) by HTTP::Request::uri at line 80 of HTTP/Request.pm, avg 170µs/call # once (50µs+5.50ms) by SimpleDB::Client::__ANON__[../lib/SimpleDB/Client.pm:120] at line 120 of ../lib/SimpleDB/Client.pm
{
3740182µs my($class, $uri, $scheme) = @_;
38
39 $uri = defined ($uri) ? "$uri" : ""; # stringify
40 # Get rid of potential wrapping
41 $uri =~ s/^<(?:URL:)?(.*)>$/$1/; #
# spent 4µs making 4 calls to URI::CORE:subst, avg 975ns/call
42 $uri =~ s/^"(.*)"$/$1/;
# spent 2µs making 4 calls to URI::CORE:subst, avg 500ns/call
43 $uri =~ s/^\s+//;
# spent 7µs making 4 calls to URI::CORE:subst, avg 2µs/call
44 $uri =~ s/\s+$//;
# spent 6µs making 4 calls to URI::CORE:subst, avg 1µs/call
45
46 my $impclass;
47 if ($uri =~ m/^($scheme_re):/so) {
# spent 27µs making 1 call to URI::CORE:regcomp # spent 12µs making 4 calls to URI::CORE:match, avg 3µs/call
48 $scheme = $1;
49 }
50 else {
51 if (($impclass = ref($scheme))) {
52 $scheme = $scheme->scheme;
53 }
54 elsif ($scheme && $scheme =~ m/^($scheme_re)(?::|$)/o) {
55 $scheme = $1;
56 }
57 }
58 $impclass ||= implementor($scheme) ||
59 do {
# spent 3.51ms making 4 calls to URI::implementor, avg 877µs/call
60 require URI::_foreign;
61 $impclass = 'URI::_foreign';
62 };
63
64 return $impclass->_init($uri, $scheme);
# spent 2.37ms making 4 calls to URI::_init, avg 592µs/call
65}
66
67
68sub new_abs
69{
70 my($class, $uri, $base) = @_;
71 $uri = $class->new($uri, $base);
72 $uri->abs($base);
73}
74
75
76sub _init
77
# spent 2.37ms (131µs+2.24) within URI::_init which was called 4 times, avg 592µs/call: # 4 times (131µs+2.24ms) by URI::new at line 64, avg 592µs/call
{
7824147µs my $class = shift;
79 my($str, $scheme) = @_;
80 # find all funny characters and encode the bytes.
81 $str = $class->_uric_escape($str);
# spent 2.22ms making 4 calls to URI::_server::_uric_escape, avg 554µs/call
82 $str = "$scheme:$str" unless $str =~ /^$scheme_re:/o ||
# spent 12µs making 1 call to URI::CORE:regcomp # spent 7µs making 4 calls to URI::CORE:match, avg 2µs/call
83 $class->_no_scheme_ok;
84 my $self = bless \$str, $class;
85 $self;
86}
87
88
89sub _uric_escape
90
# spent 39µs (27+12) within URI::_uric_escape which was called 4 times, avg 10µs/call: # 4 times (27µs+12µs) by URI::_server::_uric_escape at line 18 of URI/_server.pm, avg 10µs/call
{
911242µs my($class, $str) = @_;
92 $str =~ s*([^$uric\#])* URI::Escape::escape_char($1) *ego;
# spent 7µs making 1 call to URI::CORE:regcomp # spent 5µs making 4 calls to URI::CORE:subst, avg 1µs/call
93 return $str;
94}
95
96
97sub implementor
98
# spent 3.51ms (3.28+229µs) within URI::implementor which was called 4 times, avg 877µs/call: # 4 times (3.28ms+229µs) by URI::new at line 59, avg 877µs/call
{
9935122µs my($scheme, $impclass) = @_;
100 if (!$scheme || $scheme !~ /\A$scheme_re\z/o) {
# spent 12µs making 1 call to URI::CORE:regcomp # spent 7µs making 4 calls to URI::CORE:match, avg 2µs/call
101 require URI::_generic;
102 return "URI::_generic";
103 }
104
105 $scheme = lc($scheme);
106
107 if ($impclass) {
108 # Set the implementor class for a given scheme
109 my $old = $implements{$scheme};
110 $impclass->_init_implementor($scheme);
111 $implements{$scheme} = $impclass;
112 return $old;
113 }
114
115 my $ic = $implements{$scheme};
116 return $ic if $ic;
117
118 # scheme not yet known, look for internal or
119 # preloaded (with 'use') implementation
120 $ic = "URI::$scheme"; # default location
121
122 # turn scheme into a valid perl identifier by a simple transformation...
123 $ic =~ s/\+/_P/g;
# spent 900ns making 1 call to URI::CORE:subst
124 $ic =~ s/\./_O/g;
# spent 800ns making 1 call to URI::CORE:subst
125 $ic =~ s/\-/_/g;
# spent 600ns making 1 call to URI::CORE:subst
126
127312.9ms246µs
# spent 27µs (9+18) within URI::BEGIN@127 which was called # once (9µs+18µs) by LWP::UserAgent::BEGIN@10 at line 127
no strict 'refs';
# spent 27µs making 1 call to URI::BEGIN@127 # spent 19µs making 1 call to strict::unimport
128 # check we actually have one for the scheme:
129 unless (@{"${ic}::ISA"}) {
130 # Try to load it
1311152µs eval "require $ic";
132 die $@ if $@ && $@ !~ /Can\'t locate.*in \@INC/;
133 return unless @{"${ic}::ISA"};
134 }
135
136 $ic->_init_implementor($scheme);
# spent 3µs making 1 call to URI::_init_implementor
137 $implements{$scheme} = $ic;
138 $ic;
139}
140
141
142sub _init_implementor
143
# spent 3µs within URI::_init_implementor which was called # once (3µs+0s) by URI::implementor at line 136
{
14415µs my($class, $scheme) = @_;
145 # Remember that one implementor class may actually
146 # serve to implement several URI schemes.
147}
148
149
150sub clone
151{
152 my $self = shift;
153 my $other = $$self;
154 bless \$other, ref $self;
155}
156
157
158sub _no_scheme_ok { 0 }
159
160sub _scheme
161
# spent 123µs (75+48) within URI::_scheme which was called 9 times, avg 14µs/call: # 6 times (41µs+34µs) by URI::scheme at line 194, avg 12µs/call # 3 times (34µs+14µs) by URI::canonical at line 302, avg 16µs/call
{
16236133µs my $self = shift;
163
164 unless (@_) {
165 return unless $$self =~ /^($scheme_re):/o;
# spent 32µs making 9 calls to URI::CORE:match, avg 4µs/call # spent 16µs making 1 call to URI::CORE:regcomp
166 return $1;
167 }
168
169 my $old;
170 my $new = shift;
171 if (defined($new) && length($new)) {
172 Carp::croak("Bad scheme '$new'") unless $new =~ /^$scheme_re$/o;
173 $old = $1 if $$self =~ s/^($scheme_re)://o;
174 my $newself = URI->new("$new:$$self");
175 $$self = $$newself;
176 bless $self, ref($newself);
177 }
178 else {
179 if ($self->_no_scheme_ok) {
180 $old = $1 if $$self =~ s/^($scheme_re)://o;
181 Carp::carp("Oops, opaque part now look like scheme")
182 if $^W && $$self =~ m/^$scheme_re:/o
183 }
184 else {
185 $old = $1 if $$self =~ m/^($scheme_re):/o;
186 }
187 }
188
189 return $old;
190}
191
192sub scheme
193
# spent 116µs (41+74) within URI::scheme which was called 6 times, avg 19µs/call: # 3 times (27µs+49µs) by LWP::UserAgent::prepare_request at line 211 of LWP/UserAgent.pm, avg 25µs/call # 3 times (14µs+25µs) by LWP::UserAgent::send_request at line 120 of LWP/UserAgent.pm, avg 13µs/call
{
1941845µs674µs my $scheme = shift->_scheme(@_);
# spent 74µs making 6 calls to URI::_scheme, avg 12µs/call
195 return unless defined $scheme;
196 lc($scheme);
197}
198
199
200sub opaque
201{
202 my $self = shift;
203
204 unless (@_) {
205 $$self =~ /^(?:$scheme_re:)?([^\#]*)/o or die;
206 return $1;
207 }
208
209 $$self =~ /^($scheme_re:)? # optional scheme
210 ([^\#]*) # opaque
211 (\#.*)? # optional fragment
212 $/sx or die;
213
214 my $old_scheme = $1;
215 my $old_opaque = $2;
216 my $old_frag = $3;
217
218 my $new_opaque = shift;
219 $new_opaque = "" unless defined $new_opaque;
220 $new_opaque =~ s/([^$uric])/ URI::Escape::escape_char($1)/ego;
221
222 $$self = defined($old_scheme) ? $old_scheme : "";
223 $$self .= $new_opaque;
224 $$self .= $old_frag if defined $old_frag;
225
226 $old_opaque;
227}
228
22912µs*path = \&opaque; # alias
230
231
232sub fragment
233{
234 my $self = shift;
235 unless (@_) {
236 return unless $$self =~ /\#(.*)/s;
237 return $1;
238 }
239
240 my $old;
241 $old = $1 if $$self =~ s/\#(.*)//s;
242
243 my $new_frag = shift;
244 if (defined $new_frag) {
245 $new_frag =~ s/([^$uric])/ URI::Escape::escape_char($1) /ego;
246 $$self .= "#$new_frag";
247 }
248 $old;
249}
250
251
252sub as_string
253
# spent 12µs within URI::as_string which was called 3 times, avg 4µs/call: # 3 times (12µs+0s) by SimpleDB::Client::construct_request at line 176 of ../lib/SimpleDB/Client.pm, avg 4µs/call
{
254614µs my $self = shift;
255 $$self;
256}
257
258
259sub as_iri
260{
261 my $self = shift;
262 my $str = $$self;
263 if ($str =~ /\bxn--/ && $self->can("ihost")) {
264 my $ihost = $self->ihost;
265 if ($ihost) {
266 my $u = $self->clone;
267 $u->host("%%host%%");
268 $str = $u->as_string;
269 $str =~ s/%%host%%/$ihost/;
270 }
271 }
272 if ($str =~ s/%([89A-F][0-9A-F])/chr(hex($1))/eg) {
273 # All this crap because the more obvious:
274 #
275 # Encode::decode("UTF-8", $str, sub { sprintf "%%%02X", shift })
276 #
277 # doesn't work. Apparently passing a sub as CHECK only works
278 # for 'ascii' and similar direct encodings.
279
280 require Encode;
281 my $enc = Encode::find_encoding("UTF-8");
282 my $u = "";
283 while (length $str) {
284 $u .= $enc->decode($str, Encode::FB_QUIET());
285 if (length $str) {
286 # escape next char
287 $u .= URI::Escape::escape_char(substr($str, 0, 1, ""));
288 }
289 }
290 $str = $u;
291 }
292 return $str;
293}
294
295
296sub canonical
297
# spent 107µs (53+53) within URI::canonical which was called 3 times, avg 36µs/call: # 3 times (53µs+53µs) by URI::_server::canonical at line 145 of URI/_server.pm, avg 36µs/call
{
298 # Make sure scheme is lowercased, that we don't escape unreserved chars,
299 # and that we use upcase escape sequences.
300
3011555µs my $self = shift;
302 my $scheme = $self->_scheme || "";
# spent 49µs making 3 calls to URI::_scheme, avg 16µs/call
303 my $uc_scheme = $scheme =~ /[A-Z]/;
# spent 2µs making 3 calls to URI::CORE:match, avg 767ns/call
304 my $esc = $$self =~ /%[a-fA-F0-9]{2}/;
# spent 2µs making 3 calls to URI::CORE:match, avg 767ns/call
305 return $self unless $uc_scheme || $esc;
306
307 my $other = $self->clone;
308 if ($uc_scheme) {
309 $other->_scheme(lc $scheme);
310 }
311 if ($esc) {
312 $$other =~ s{%([0-9a-fA-F]{2})}
313 { my $a = chr(hex($1));
314 $a =~ /^[$unreserved]\z/o ? $a : "%\U$1"
315 }ge;
316 }
317 return $other;
318}
319
320# Compare two URIs, subclasses will provide a more correct implementation
321sub eq {
322 my($self, $other) = @_;
323 $self = URI->new($self, $other) unless ref $self;
324 $other = URI->new($other, $self) unless ref $other;
325 ref($self) eq ref($other) && # same class
326 $self->canonical->as_string eq $other->canonical->as_string;
327}
328
329# generic-URI transformation methods
330sub abs { $_[0]; }
331sub rel { $_[0]; }
332
333# help out Storable
334sub STORABLE_freeze {
335 my($self, $cloning) = @_;
336 return $$self;
337}
338
339sub STORABLE_thaw {
340 my($self, $cloning, $str) = @_;
341 $$self = $str;
342}
343
344116µs1;
345
346__END__
347
348=head1 NAME
349
350URI - Uniform Resource Identifiers (absolute and relative)
351
352=head1 SYNOPSIS
353
354 $u1 = URI->new("http://www.perl.com");
355 $u2 = URI->new("foo", "http");
356 $u3 = $u2->abs($u1);
357 $u4 = $u3->clone;
358 $u5 = URI->new("HTTP://WWW.perl.com:80")->canonical;
359
360 $str = $u->as_string;
361 $str = "$u";
362
363 $scheme = $u->scheme;
364 $opaque = $u->opaque;
365 $path = $u->path;
366 $frag = $u->fragment;
367
368 $u->scheme("ftp");
369 $u->host("ftp.perl.com");
370 $u->path("cpan/");
371
372=head1 DESCRIPTION
373
374This module implements the C<URI> class. Objects of this class
375represent "Uniform Resource Identifier references" as specified in RFC
3762396 (and updated by RFC 2732).
377
378A Uniform Resource Identifier is a compact string of characters that
379identifies an abstract or physical resource. A Uniform Resource
380Identifier can be further classified as either a Uniform Resource Locator
381(URL) or a Uniform Resource Name (URN). The distinction between URL
382and URN does not matter to the C<URI> class interface. A
383"URI-reference" is a URI that may have additional information attached
384in the form of a fragment identifier.
385
386An absolute URI reference consists of three parts: a I<scheme>, a
387I<scheme-specific part> and a I<fragment> identifier. A subset of URI
388references share a common syntax for hierarchical namespaces. For
389these, the scheme-specific part is further broken down into
390I<authority>, I<path> and I<query> components. These URIs can also
391take the form of relative URI references, where the scheme (and
392usually also the authority) component is missing, but implied by the
393context of the URI reference. The three forms of URI reference
394syntax are summarized as follows:
395
396 <scheme>:<scheme-specific-part>#<fragment>
397 <scheme>://<authority><path>?<query>#<fragment>
398 <path>?<query>#<fragment>
399
400The components into which a URI reference can be divided depend on the
401I<scheme>. The C<URI> class provides methods to get and set the
402individual components. The methods available for a specific
403C<URI> object depend on the scheme.
404
405=head1 CONSTRUCTORS
406
407The following methods construct new C<URI> objects:
408
409=over 4
410
411=item $uri = URI->new( $str )
412
413=item $uri = URI->new( $str, $scheme )
414
415Constructs a new URI object. The string
416representation of a URI is given as argument, together with an optional
417scheme specification. Common URI wrappers like "" and <>, as well as
418leading and trailing white space, are automatically removed from
419the $str argument before it is processed further.
420
421The constructor determines the scheme, maps this to an appropriate
422URI subclass, constructs a new object of that class and returns it.
423
424The $scheme argument is only used when $str is a
425relative URI. It can be either a simple string that
426denotes the scheme, a string containing an absolute URI reference, or
427an absolute C<URI> object. If no $scheme is specified for a relative
428URI $str, then $str is simply treated as a generic URI (no scheme-specific
429methods available).
430
431The set of characters available for building URI references is
432restricted (see L<URI::Escape>). Characters outside this set are
433automatically escaped by the URI constructor.
434
435=item $uri = URI->new_abs( $str, $base_uri )
436
437Constructs a new absolute URI object. The $str argument can
438denote a relative or absolute URI. If relative, then it is
439absolutized using $base_uri as base. The $base_uri must be an absolute
440URI.
441
442=item $uri = URI::file->new( $filename )
443
444=item $uri = URI::file->new( $filename, $os )
445
446Constructs a new I<file> URI from a file name. See L<URI::file>.
447
448=item $uri = URI::file->new_abs( $filename )
449
450=item $uri = URI::file->new_abs( $filename, $os )
451
452Constructs a new absolute I<file> URI from a file name. See
453L<URI::file>.
454
455=item $uri = URI::file->cwd
456
457Returns the current working directory as a I<file> URI. See
458L<URI::file>.
459
460=item $uri->clone
461
462Returns a copy of the $uri.
463
464=back
465
466=head1 COMMON METHODS
467
468The methods described in this section are available for all C<URI>
469objects.
470
471Methods that give access to components of a URI always return the
472old value of the component. The value returned is C<undef> if the
473component was not present. There is generally a difference between a
474component that is empty (represented as C<"">) and a component that is
475missing (represented as C<undef>). If an accessor method is given an
476argument, it updates the corresponding component in addition to
477returning the old value of the component. Passing an undefined
478argument removes the component (if possible). The description of
479each accessor method indicates whether the component is passed as
480an escaped or an unescaped string. A component that can be further
481divided into sub-parts are usually passed escaped, as unescaping might
482change its semantics.
483
484The common methods available for all URI are:
485
486=over 4
487
488=item $uri->scheme
489
490=item $uri->scheme( $new_scheme )
491
492Sets and returns the scheme part of the $uri. If the $uri is
493relative, then $uri->scheme returns C<undef>. If called with an
494argument, it updates the scheme of $uri, possibly changing the
495class of $uri, and returns the old scheme value. The method croaks
496if the new scheme name is illegal; a scheme name must begin with a
497letter and must consist of only US-ASCII letters, numbers, and a few
498special marks: ".", "+", "-". This restriction effectively means
499that the scheme must be passed unescaped. Passing an undefined
500argument to the scheme method makes the URI relative (if possible).
501
502Letter case does not matter for scheme names. The string
503returned by $uri->scheme is always lowercase. If you want the scheme
504just as it was written in the URI in its original case,
505you can use the $uri->_scheme method instead.
506
507=item $uri->opaque
508
509=item $uri->opaque( $new_opaque )
510
511Sets and returns the scheme-specific part of the $uri
512(everything between the scheme and the fragment)
513as an escaped string.
514
515=item $uri->path
516
517=item $uri->path( $new_path )
518
519Sets and returns the same value as $uri->opaque unless the URI
520supports the generic syntax for hierarchical namespaces.
521In that case the generic method is overridden to set and return
522the part of the URI between the I<host name> and the I<fragment>.
523
524=item $uri->fragment
525
526=item $uri->fragment( $new_frag )
527
528Returns the fragment identifier of a URI reference
529as an escaped string.
530
531=item $uri->as_string
532
533Returns a URI object to a plain ASCII string. URI objects are
534also converted to plain strings automatically by overloading. This
535means that $uri objects can be used as plain strings in most Perl
536constructs.
537
538=item $uri->as_iri
539
540Returns a Unicode string representing the URI. Escaped UTF-8 sequences
541representing non-ASCII characters are turned into their corresponding Unicode
542code point.
543
544=item $uri->canonical
545
546Returns a normalized version of the URI. The rules
547for normalization are scheme-dependent. They usually involve
548lowercasing the scheme and Internet host name components,
549removing the explicit port specification if it matches the default port,
550uppercasing all escape sequences, and unescaping octets that can be
551better represented as plain characters.
552
553For efficiency reasons, if the $uri is already in normalized form,
554then a reference to it is returned instead of a copy.
555
556=item $uri->eq( $other_uri )
557
558=item URI::eq( $first_uri, $other_uri )
559
560Tests whether two URI references are equal. URI references
561that normalize to the same string are considered equal. The method
562can also be used as a plain function which can also test two string
563arguments.
564
565If you need to test whether two C<URI> object references denote the
566same object, use the '==' operator.
567
568=item $uri->abs( $base_uri )
569
570Returns an absolute URI reference. If $uri is already
571absolute, then a reference to it is simply returned. If the $uri
572is relative, then a new absolute URI is constructed by combining the
573$uri and the $base_uri, and returned.
574
575=item $uri->rel( $base_uri )
576
577Returns a relative URI reference if it is possible to
578make one that denotes the same resource relative to $base_uri.
579If not, then $uri is simply returned.
580
581=back
582
583=head1 GENERIC METHODS
584
585The following methods are available to schemes that use the
586common/generic syntax for hierarchical namespaces. The descriptions of
587schemes below indicate which these are. Unknown schemes are
588assumed to support the generic syntax, and therefore the following
589methods:
590
591=over 4
592
593=item $uri->authority
594
595=item $uri->authority( $new_authority )
596
597Sets and returns the escaped authority component
598of the $uri.
599
600=item $uri->path
601
602=item $uri->path( $new_path )
603
604Sets and returns the escaped path component of
605the $uri (the part between the host name and the query or fragment).
606The path can never be undefined, but it can be the empty string.
607
608=item $uri->path_query
609
610=item $uri->path_query( $new_path_query )
611
612Sets and returns the escaped path and query
613components as a single entity. The path and the query are
614separated by a "?" character, but the query can itself contain "?".
615
616=item $uri->path_segments
617
618=item $uri->path_segments( $segment, ... )
619
620Sets and returns the path. In a scalar context, it returns
621the same value as $uri->path. In a list context, it returns the
622unescaped path segments that make up the path. Path segments that
623have parameters are returned as an anonymous array. The first element
624is the unescaped path segment proper; subsequent elements are escaped
625parameter strings. Such an anonymous array uses overloading so it can
626be treated as a string too, but this string does not include the
627parameters.
628
629Note that absolute paths have the empty string as their first
630I<path_segment>, i.e. the I<path> C</foo/bar> have 3
631I<path_segments>; "", "foo" and "bar".
632
633=item $uri->query
634
635=item $uri->query( $new_query )
636
637Sets and returns the escaped query component of
638the $uri.
639
640=item $uri->query_form
641
642=item $uri->query_form( $key1 => $val1, $key2 => $val2, ... )
643
644=item $uri->query_form( $key1 => $val1, $key2 => $val2, ..., $delim )
645
646=item $uri->query_form( \@key_value_pairs )
647
648=item $uri->query_form( \@key_value_pairs, $delim )
649
650=item $uri->query_form( \%hash )
651
652=item $uri->query_form( \%hash, $delim )
653
654Sets and returns query components that use the
655I<application/x-www-form-urlencoded> format. Key/value pairs are
656separated by "&", and the key is separated from the value by a "="
657character.
658
659The form can be set either by passing separate key/value pairs, or via
660an array or hash reference. Passing an empty array or an empty hash
661removes the query component, whereas passing no arguments at all leaves
662the component unchanged. The order of keys is undefined if a hash
663reference is passed. The old value is always returned as a list of
664separate key/value pairs. Assigning this list to a hash is unwise as
665the keys returned might repeat.
666
667The values passed when setting the form can be plain strings or
668references to arrays of strings. Passing an array of values has the
669same effect as passing the key repeatedly with one value at a time.
670All the following statements have the same effect:
671
672 $uri->query_form(foo => 1, foo => 2);
673 $uri->query_form(foo => [1, 2]);
674 $uri->query_form([ foo => 1, foo => 2 ]);
675 $uri->query_form([ foo => [1, 2] ]);
676 $uri->query_form({ foo => [1, 2] });
677
678The $delim parameter can be passed as ";" to force the key/value pairs
679to be delimited by ";" instead of "&" in the query string. This
680practice is often recommended for URLs embedded in HTML or XML
681documents as this avoids the trouble of escaping the "&" character.
682You might also set the $URI::DEFAULT_QUERY_FORM_DELIMITER variable to
683";" for the same global effect.
684
685The C<URI::QueryParam> module can be loaded to add further methods to
686manipulate the form of a URI. See L<URI::QueryParam> for details.
687
688=item $uri->query_keywords
689
690=item $uri->query_keywords( $keywords, ... )
691
692=item $uri->query_keywords( \@keywords )
693
694Sets and returns query components that use the
695keywords separated by "+" format.
696
697The keywords can be set either by passing separate keywords directly
698or by passing a reference to an array of keywords. Passing an empty
699array removes the query component, whereas passing no arguments at
700all leaves the component unchanged. The old value is always returned
701as a list of separate words.
702
703=back
704
705=head1 SERVER METHODS
706
707For schemes where the I<authority> component denotes an Internet host,
708the following methods are available in addition to the generic
709methods.
710
711=over 4
712
713=item $uri->userinfo
714
715=item $uri->userinfo( $new_userinfo )
716
717Sets and returns the escaped userinfo part of the
718authority component.
719
720For some schemes this is a user name and a password separated by
721a colon. This practice is not recommended. Embedding passwords in
722clear text (such as URI) has proven to be a security risk in almost
723every case where it has been used.
724
725=item $uri->host
726
727=item $uri->host( $new_host )
728
729Sets and returns the unescaped hostname.
730
731If the $new_host string ends with a colon and a number, then this
732number also sets the port.
733
734For IPv6 addresses the brackets around the raw address is removed in the return
735value from $uri->host. When setting the host attribute to an IPv6 address you
736can use a raw address or one enclosed in brackets. The address needs to be
737enclosed in brackets if you want to pass in a new port value as well.
738
739=item $uri->ihost
740
741Returns the host in Unicode form. Any IDNA A-labels are turned into U-labels.
742
743=item $uri->port
744
745=item $uri->port( $new_port )
746
747Sets and returns the port. The port is a simple integer
748that should be greater than 0.
749
750If a port is not specified explicitly in the URI, then the URI scheme's default port
751is returned. If you don't want the default port
752substituted, then you can use the $uri->_port method instead.
753
754=item $uri->host_port
755
756=item $uri->host_port( $new_host_port )
757
758Sets and returns the host and port as a single
759unit. The returned value includes a port, even if it matches the
760default port. The host part and the port part are separated by a
761colon: ":".
762
763For IPv6 addresses the bracketing is preserved; thus
764URI->new("http://[::1]/")->host_port returns "[::1]:80". Contrast this with
765$uri->host which will remove the brackets.
766
767=item $uri->default_port
768
769Returns the default port of the URI scheme to which $uri
770belongs. For I<http> this is the number 80, for I<ftp> this
771is the number 21, etc. The default port for a scheme can not be
772changed.
773
774=back
775
776=head1 SCHEME-SPECIFIC SUPPORT
777
778Scheme-specific support is provided for the following URI schemes. For C<URI>
779objects that do not belong to one of these, you can only use the common and
780generic methods.
781
782=over 4
783
784=item B<data>:
785
786The I<data> URI scheme is specified in RFC 2397. It allows inclusion
787of small data items as "immediate" data, as if it had been included
788externally.
789
790C<URI> objects belonging to the data scheme support the common methods
791and two new methods to access their scheme-specific components:
792$uri->media_type and $uri->data. See L<URI::data> for details.
793
794=item B<file>:
795
796An old specification of the I<file> URI scheme is found in RFC 1738.
797A new RFC 2396 based specification in not available yet, but file URI
798references are in common use.
799
800C<URI> objects belonging to the file scheme support the common and
801generic methods. In addition, they provide two methods for mapping file URIs
802back to local file names; $uri->file and $uri->dir. See L<URI::file>
803for details.
804
805=item B<ftp>:
806
807An old specification of the I<ftp> URI scheme is found in RFC 1738. A
808new RFC 2396 based specification in not available yet, but ftp URI
809references are in common use.
810
811C<URI> objects belonging to the ftp scheme support the common,
812generic and server methods. In addition, they provide two methods for
813accessing the userinfo sub-components: $uri->user and $uri->password.
814
815=item B<gopher>:
816
817The I<gopher> URI scheme is specified in
818<draft-murali-url-gopher-1996-12-04> and will hopefully be available
819as a RFC 2396 based specification.
820
821C<URI> objects belonging to the gopher scheme support the common,
822generic and server methods. In addition, they support some methods for
823accessing gopher-specific path components: $uri->gopher_type,
824$uri->selector, $uri->search, $uri->string.
825
826=item B<http>:
827
828The I<http> URI scheme is specified in RFC 2616.
829The scheme is used to reference resources hosted by HTTP servers.
830
831C<URI> objects belonging to the http scheme support the common,
832generic and server methods.
833
834=item B<https>:
835
836The I<https> URI scheme is a Netscape invention which is commonly
837implemented. The scheme is used to reference HTTP servers through SSL
838connections. Its syntax is the same as http, but the default
839port is different.
840
841=item B<ldap>:
842
843The I<ldap> URI scheme is specified in RFC 2255. LDAP is the
844Lightweight Directory Access Protocol. An ldap URI describes an LDAP
845search operation to perform to retrieve information from an LDAP
846directory.
847
848C<URI> objects belonging to the ldap scheme support the common,
849generic and server methods as well as ldap-specific methods: $uri->dn,
850$uri->attributes, $uri->scope, $uri->filter, $uri->extensions. See
851L<URI::ldap> for details.
852
853=item B<ldapi>:
854
855Like the I<ldap> URI scheme, but uses a UNIX domain socket. The
856server methods are not supported, and the local socket path is
857available as $uri->un_path. The I<ldapi> scheme is used by the
858OpenLDAP package. There is no real specification for it, but it is
859mentioned in various OpenLDAP manual pages.
860
861=item B<ldaps>:
862
863Like the I<ldap> URI scheme, but uses an SSL connection. This
864scheme is deprecated, as the preferred way is to use the I<start_tls>
865mechanism.
866
867=item B<mailto>:
868
869The I<mailto> URI scheme is specified in RFC 2368. The scheme was
870originally used to designate the Internet mailing address of an
871individual or service. It has (in RFC 2368) been extended to allow
872setting of other mail header fields and the message body.
873
874C<URI> objects belonging to the mailto scheme support the common
875methods and the generic query methods. In addition, they support the
876following mailto-specific methods: $uri->to, $uri->headers.
877
878Note that the "foo@example.com" part of a mailto is I<not> the
879C<userinfo> and C<host> but instead the C<path>. This allowed a
880mailto to contain multiple comma-seperated email addresses.
881
882=item B<mms>:
883
884The I<mms> URL specification can be found at L<http://sdp.ppona.com/>
885C<URI> objects belonging to the mms scheme support the common,
886generic, and server methods, with the exception of userinfo and
887query-related sub-components.
888
889=item B<news>:
890
891The I<news>, I<nntp> and I<snews> URI schemes are specified in
892<draft-gilman-news-url-01> and will hopefully be available as an RFC
8932396 based specification soon.
894
895C<URI> objects belonging to the news scheme support the common,
896generic and server methods. In addition, they provide some methods to
897access the path: $uri->group and $uri->message.
898
899=item B<nntp>:
900
901See I<news> scheme.
902
903=item B<pop>:
904
905The I<pop> URI scheme is specified in RFC 2384. The scheme is used to
906reference a POP3 mailbox.
907
908C<URI> objects belonging to the pop scheme support the common, generic
909and server methods. In addition, they provide two methods to access the
910userinfo components: $uri->user and $uri->auth
911
912=item B<rlogin>:
913
914An old specification of the I<rlogin> URI scheme is found in RFC
9151738. C<URI> objects belonging to the rlogin scheme support the
916common, generic and server methods.
917
918=item B<rtsp>:
919
920The I<rtsp> URL specification can be found in section 3.2 of RFC 2326.
921C<URI> objects belonging to the rtsp scheme support the common,
922generic, and server methods, with the exception of userinfo and
923query-related sub-components.
924
925=item B<rtspu>:
926
927The I<rtspu> URI scheme is used to talk to RTSP servers over UDP
928instead of TCP. The syntax is the same as rtsp.
929
930=item B<rsync>:
931
932Information about rsync is available from http://rsync.samba.org.
933C<URI> objects belonging to the rsync scheme support the common,
934generic and server methods. In addition, they provide methods to
935access the userinfo sub-components: $uri->user and $uri->password.
936
937=item B<sip>:
938
939The I<sip> URI specification is described in sections 19.1 and 25
940of RFC 3261. C<URI> objects belonging to the sip scheme support the
941common, generic, and server methods with the exception of path related
942sub-components. In addition, they provide two methods to get and set
943I<sip> parameters: $uri->params_form and $uri->params.
944
945=item B<sips>:
946
947See I<sip> scheme. Its syntax is the same as sip, but the default
948port is different.
949
950=item B<snews>:
951
952See I<news> scheme. Its syntax is the same as news, but the default
953port is different.
954
955=item B<telnet>:
956
957An old specification of the I<telnet> URI scheme is found in RFC
9581738. C<URI> objects belonging to the telnet scheme support the
959common, generic and server methods.
960
961=item B<tn3270>:
962
963These URIs are used like I<telnet> URIs but for connections to IBM
964mainframes. C<URI> objects belonging to the tn3270 scheme support the
965common, generic and server methods.
966
967=item B<ssh>:
968
969Information about ssh is available at http://www.openssh.com/.
970C<URI> objects belonging to the ssh scheme support the common,
971generic and server methods. In addition, they provide methods to
972access the userinfo sub-components: $uri->user and $uri->password.
973
974=item B<urn>:
975
976The syntax of Uniform Resource Names is specified in RFC 2141. C<URI>
977objects belonging to the urn scheme provide the common methods, and also the
978methods $uri->nid and $uri->nss, which return the Namespace Identifier
979and the Namespace-Specific String respectively.
980
981The Namespace Identifier basically works like the Scheme identifier of
982URIs, and further divides the URN namespace. Namespace Identifier
983assignments are maintained at
984<http://www.iana.org/assignments/urn-namespaces>.
985
986Letter case is not significant for the Namespace Identifier. It is
987always returned in lower case by the $uri->nid method. The $uri->_nid
988method can be used if you want it in its original case.
989
990=item B<urn>:B<isbn>:
991
992The C<urn:isbn:> namespace contains International Standard Book
993Numbers (ISBNs) and is described in RFC 3187. A C<URI> object belonging
994to this namespace has the following extra methods (if the
995Business::ISBN module is available): $uri->isbn,
996$uri->isbn_publisher_code, $uri->isbn_group_code (formerly isbn_country_code,
997which is still supported by issues a deprecation warning), $uri->isbn_as_ean.
998
999=item B<urn>:B<oid>:
1000
1001The C<urn:oid:> namespace contains Object Identifiers (OIDs) and is
1002described in RFC 3061. An object identifier consists of sequences of digits
1003separated by dots. A C<URI> object belonging to this namespace has an
1004additional method called $uri->oid that can be used to get/set the oid
1005value. In a list context, oid numbers are returned as separate elements.
1006
1007=back
1008
1009=head1 CONFIGURATION VARIABLES
1010
1011The following configuration variables influence how the class and its
1012methods behave:
1013
1014=over 4
1015
1016=item $URI::ABS_ALLOW_RELATIVE_SCHEME
1017
1018Some older parsers used to allow the scheme name to be present in the
1019relative URL if it was the same as the base URL scheme. RFC 2396 says
1020that this should be avoided, but you can enable this old behaviour by
1021setting the $URI::ABS_ALLOW_RELATIVE_SCHEME variable to a TRUE value.
1022The difference is demonstrated by the following examples:
1023
1024 URI->new("http:foo")->abs("http://host/a/b")
1025 ==> "http:foo"
1026
1027 local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1;
1028 URI->new("http:foo")->abs("http://host/a/b")
1029 ==> "http:/host/a/foo"
1030
1031
1032=item $URI::ABS_REMOTE_LEADING_DOTS
1033
1034You can also have the abs() method ignore excess ".."
1035segments in the relative URI by setting $URI::ABS_REMOTE_LEADING_DOTS
1036to a TRUE value. The difference is demonstrated by the following
1037examples:
1038
1039 URI->new("../../../foo")->abs("http://host/a/b")
1040 ==> "http://host/../../foo"
1041
1042 local $URI::ABS_REMOTE_LEADING_DOTS = 1;
1043 URI->new("../../../foo")->abs("http://host/a/b")
1044 ==> "http://host/foo"
1045
1046=item $URI::DEFAULT_QUERY_FORM_DELIMITER
1047
1048This value can be set to ";" to have the query form C<key=value> pairs
1049delimited by ";" instead of "&" which is the default.
1050
1051=back
1052
1053=head1 BUGS
1054
1055Using regexp variables like $1 directly as arguments to the URI methods
1056does not work too well with current perl implementations. I would argue
1057that this is actually a bug in perl. The workaround is to quote
1058them. Example:
1059
1060 /(...)/ || die;
1061 $u->query("$1");
1062
1063=head1 PARSING URIs WITH REGEXP
1064
1065As an alternative to this module, the following (official) regular
1066expression can be used to decode a URI:
1067
1068 my($scheme, $authority, $path, $query, $fragment) =
1069 $uri =~ m|(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?|;
1070
1071The C<URI::Split> module provides the function uri_split() as a
1072readable alternative.
1073
1074=head1 SEE ALSO
1075
1076L<URI::file>, L<URI::WithBase>, L<URI::QueryParam>, L<URI::Escape>,
1077L<URI::Split>, L<URI::Heuristic>
1078
1079RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax",
1080Berners-Lee, Fielding, Masinter, August 1998.
1081
1082http://www.iana.org/assignments/uri-schemes
1083
1084http://www.iana.org/assignments/urn-namespaces
1085
1086http://www.w3.org/Addressing/
1087
1088=head1 COPYRIGHT
1089
1090Copyright 1995-2009 Gisle Aas.
1091
1092Copyright 1995 Martijn Koster.
1093
1094This program is free software; you can redistribute it and/or modify
1095it under the same terms as Perl itself.
1096
1097=head1 AUTHORS / ACKNOWLEDGMENTS
1098
1099This module is based on the C<URI::URL> module, which in turn was
1100(distantly) based on the C<wwwurl.pl> code in the libwww-perl for
1101perl4 developed by Roy Fielding, as part of the Arcadia project at the
1102University of California, Irvine, with contributions from Brooks
1103Cutter.
1104
1105C<URI::URL> was developed by Gisle Aas, Tim Bunce, Roy Fielding and
1106Martijn Koster with input from other people on the libwww-perl mailing
1107list.
1108
1109C<URI> and related subclasses was developed by Gisle Aas.
1110
1111=cut
# spent 63µs within URI::CORE:match which was called 27 times, avg 2µs/call: # 9 times (32µs+0s) by URI::_scheme at line 165 of URI.pm, avg 4µs/call # 4 times (12µs+0s) by URI::new at line 47 of URI.pm, avg 3µs/call # 4 times (7µs+0s) by URI::implementor at line 100 of URI.pm, avg 2µs/call # 4 times (7µs+0s) by URI::_init at line 82 of URI.pm, avg 2µs/call # 3 times (2µs+0s) by URI::canonical at line 304 of URI.pm, avg 767ns/call # 3 times (2µs+0s) by URI::canonical at line 303 of URI.pm, avg 767ns/call
sub URI::CORE:match; # xsub
# spent 74µs within URI::CORE:regcomp which was called 5 times, avg 15µs/call: # once (27µs+0s) by URI::new at line 47 of URI.pm # once (16µs+0s) by URI::_scheme at line 165 of URI.pm # once (12µs+0s) by URI::_init at line 82 of URI.pm # once (12µs+0s) by URI::implementor at line 100 of URI.pm # once (7µs+0s) by URI::_uric_escape at line 92 of URI.pm
sub URI::CORE:regcomp; # xsub
# spent 26µs within URI::CORE:subst which was called 23 times, avg 1µs/call: # 4 times (7µs+0s) by URI::new at line 43 of URI.pm, avg 2µs/call # 4 times (6µs+0s) by URI::new at line 44 of URI.pm, avg 1µs/call # 4 times (5µs+0s) by URI::_uric_escape at line 92 of URI.pm, avg 1µs/call # 4 times (4µs+0s) by URI::new at line 41 of URI.pm, avg 975ns/call # 4 times (2µs+0s) by URI::new at line 42 of URI.pm, avg 500ns/call # once (900ns+0s) by URI::implementor at line 123 of URI.pm # once (800ns+0s) by URI::implementor at line 124 of URI.pm # once (600ns+0s) by URI::implementor at line 125 of URI.pm
sub URI::CORE:subst; # xsub