Profile of /project/perl/lib/URI.pm

File	/project/perl/lib/URI.pm
Statements Executed	20791
Statement Execution Time	278ms

Subroutines — ordered by exclusive time
Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
461	1	1	61.0ms	151ms	URI::::newURI::new
1383	1	1	52.0ms	64.6ms	URI::::_schemeURI::_scheme
1383	3	1	50.0ms	115ms	URI::::schemeURI::scheme
461	1	1	30.6ms	38.2ms	URI::::_initURI::_init
461	1	1	30.5ms	34.3ms	URI::::implementorURI::implementor
2766	4	2	23.6ms	23.6ms	URI::::CORE:matchURI::CORE:match (opcode)
2308	8	2	16.7ms	16.7ms	URI::::CORE:substURI::CORE:subst (opcode)
5	5	2	138µs	138µs	URI::::CORE:regcompURI::CORE:regcomp (opcode)
1	1	1	16µs	16µs	URI::::_init_implementorURI::_init_implementor
0	0	0	0s	0s	URI::::BEGINURI::BEGIN
0	0	0	0s	0s	URI::::STORABLE_freezeURI::STORABLE_freeze
0	0	0	0s	0s	URI::::STORABLE_thawURI::STORABLE_thaw
0	0	0	0s	0s	URI::::__ANON__[:24]URI::__ANON__[:24]
0	0	0	0s	0s	URI::::__ANON__[:27]URI::__ANON__[:27]
0	0	0	0s	0s	URI::::_no_scheme_okURI::_no_scheme_ok
0	0	0	0s	0s	URI::::absURI::abs
0	0	0	0s	0s	URI::::as_stringURI::as_string
0	0	0	0s	0s	URI::::canonicalURI::canonical
0	0	0	0s	0s	URI::::cloneURI::clone
0	0	0	0s	0s	URI::::eqURI::eq
0	0	0	0s	0s	URI::::fragmentURI::fragment
0	0	0	0s	0s	URI::::new_absURI::new_abs
0	0	0	0s	0s	URI::::opaqueURI::opaque
0	0	0	0s	0s	URI::::relURI::rel

Call graph for these subroutines as a Graphviz dot language file.

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