Profile of /usr/local/lib/perl5/site_perl/5.10.1/URI.pm

← 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
--- | --- | --- | --- | --- | ---
4 | 1 | 1 | 3.28ms | 3.51ms | URI::::implementorURI::implementor
1 | 1 | 1 | 882µs | 976µs | URI::::BEGIN@22URI::BEGIN@22
4 | 1 | 1 | 131µs | 2.37ms | URI::::_initURI::_init
4 | 2 | 2 | 130µs | 6.06ms | URI::::newURI::new
9 | 2 | 1 | 75µs | 123µs | URI::::_schemeURI::_scheme
5 | 5 | 2 | 74µs | 74µs | URI::::CORE:regcompURI::CORE:regcomp (opcode)
27 | 6 | 2 | 63µs | 63µs | URI::::CORE:matchURI::CORE:match (opcode)
3 | 1 | 1 | 53µs | 107µs | URI::::canonicalURI::canonical
6 | 2 | 1 | 41µs | 116µs | URI::::schemeURI::scheme
4 | 1 | 1 | 27µs | 39µs | URI::::_uric_escapeURI::_uric_escape
23 | 8 | 2 | 26µs | 26µs | URI::::CORE:substURI::CORE:subst (opcode)
1 | 1 | 1 | 16µs | 67µs | URI::::BEGIN@24URI::BEGIN@24
1 | 1 | 1 | 14µs | 17µs | URI::::BEGIN@3URI::BEGIN@3
3 | 1 | 1 | 12µs | 12µs | URI::::as_stringURI::as_string
3 | 1 | 1 | 9µs | 9µs | URI::::__ANON__[:24]URI::__ANON__[:24]
1 | 1 | 1 | 9µs | 27µs | URI::::BEGIN@127URI::BEGIN@127
1 | 1 | 1 | 6µs | 23µs | URI::::BEGIN@4URI::BEGIN@4
1 | 1 | 1 | 6µs | 39µs | URI::::BEGIN@7URI::BEGIN@7
1 | 1 | 1 | 6µs | 55µs | URI::::BEGIN@13URI::BEGIN@13
1 | 1 | 1 | 3µs | 3µs | URI::::BEGIN@21URI::BEGIN@21
1 | 1 | 1 | 3µs | 3µs | URI::::_init_implementorURI::_init_implementor
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__[:25]URI::__ANON__[:25]
0 | 0 | 0 | 0s | 0s | URI::::__ANON__[:26]URI::__ANON__[:26]
0 | 0 | 0 | 0s | 0s | URI::::_no_scheme_okURI::_no_scheme_ok
0 | 0 | 0 | 0s | 0s | URI::::_obj_eqURI::_obj_eq
0 | 0 | 0 | 0s | 0s | URI::::absURI::abs
0 | 0 | 0 | 0s | 0s | URI::::as_iriURI::as_iri
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 | 24µs | 2 | 20µ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
4 | 3 | 28µs | 2 | 41µ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
5 | 1 | 1µs |  |  | $VERSION = "1.51";
6 |  |  |  |  |
7 | 3 | 27µs | 2 | 73µ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 |  |  |  |  |
9 | 1 | 200ns |  |  | my %implements; # mapping from scheme to implementor class
10 |  |  |  |  |
11 |  |  |  |  | # Some "official" character classes
12 |  |  |  |  |
13 | 3 | 49µs | 2 | 104µ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
14 | 1 | 400ns |  |  | $reserved = q(;/?:@&=+$,[]);
15 | 1 | 500ns |  |  | $mark = q(-_.!~*'()); #'; emacs
16 | 1 | 3µs |  |  | $unreserved = "A-Za-z0-9\Q$mark\E";
17 | 1 | 2µs |  |  | $uric = quotemeta($reserved) . $unreserved . "%";
18 |  |  |  |  |
19 | 1 | 300ns |  |  | $scheme_re = '[a-zA-Z][a-zA-Z0-9.+\-]*';
20 |  |  |  |  |
21 | 3 | 17µs | 1 | 3µ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
22 | 3 | 182µs | 1 | 976µ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 |  |  |  |  |
24 | 3 | 13µ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
28 | 3 | 420µs | 1 | 67µs | ); # spent 67µs making 1 call to URI::BEGIN@24
29 |  |  |  |  |
30 |  |  |  |  | # Check if two objects are the same object
31 |  |  |  |  | sub _obj_eq {
32 |  |  |  |  | return overload::StrVal($_[0]) eq overload::StrVal($_[1]);
33 |  |  |  |  | }
34 |  |  |  |  |
35 |  |  |  |  | sub 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 {
37 | 40 | 182µ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 |  |  |  |  |
68 |  |  |  |  | sub new_abs
69 |  |  |  |  | {
70 |  |  |  |  | my($class, $uri, $base) = @_;
71 |  |  |  |  | $uri = $class->new($uri, $base);
72 |  |  |  |  | $uri->abs($base);
73 |  |  |  |  | }
74 |  |  |  |  |
75 |  |  |  |  |
76 |  |  |  |  | sub _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 {
78 | 24 | 147µ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 |  |  |  |  |
89 |  |  |  |  | sub _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 {
91 | 12 | 42µ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 |  |  |  |  |
97 |  |  |  |  | sub 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 {
99 | 35 | 122µ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 |  |  |  |  |
127 | 3 | 12.9ms | 2 | 46µ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
131 | 1 | 152µ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 |  |  |  |  |
142 |  |  |  |  | sub _init_implementor
143 |  |  |  |  | # spent 3µs within URI::_init_implementor which was called # once (3µs+0s) by URI::implementor at line 136 {
144 | 1 | 5µs |  |  | my($class, $scheme) = @_;
145 |  |  |  |  | # Remember that one implementor class may actually
146 |  |  |  |  | # serve to implement several URI schemes.
147 |  |  |  |  | }
148 |  |  |  |  |
149 |  |  |  |  |
150 |  |  |  |  | sub clone
151 |  |  |  |  | {
152 |  |  |  |  | my $self = shift;
153 |  |  |  |  | my $other = $$self;
154 |  |  |  |  | bless \$other, ref $self;
155 |  |  |  |  | }
156 |  |  |  |  |
157 |  |  |  |  |
158 |  |  |  |  | sub _no_scheme_ok { 0 }
159 |  |  |  |  |
160 |  |  |  |  | sub _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 {
162 | 36 | 133µ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 |  |  |  |  |
192 |  |  |  |  | sub 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 {
194 | 18 | 45µs | 6 | 74µ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 |  |  |  |  |
200 |  |  |  |  | sub 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 |  |  |  |  |
229 | 1 | 2µs |  |  | *path = \&opaque; # alias
230 |  |  |  |  |
231 |  |  |  |  |
232 |  |  |  |  | sub 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 |  |  |  |  |
252 |  |  |  |  | sub 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 {
254 | 6 | 14µs |  |  | my $self = shift;
255 |  |  |  |  | $$self;
256 |  |  |  |  | }
257 |  |  |  |  |
258 |  |  |  |  |
259 |  |  |  |  | sub 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 |  |  |  |  |
296 |  |  |  |  | sub 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 |  |  |  |  |
301 | 15 | 55µ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
321 |  |  |  |  | sub 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
330 |  |  |  |  | sub abs { $_[0]; }
331 |  |  |  |  | sub rel { $_[0]; }
332 |  |  |  |  |
333 |  |  |  |  | # help out Storable
334 |  |  |  |  | sub STORABLE_freeze {
335 |  |  |  |  | my($self, $cloning) = @_;
336 |  |  |  |  | return $$self;
337 |  |  |  |  | }
338 |  |  |  |  |
339 |  |  |  |  | sub STORABLE_thaw {
340 |  |  |  |  | my($self, $cloning, $str) = @_;
341 |  |  |  |  | $$self = $str;
342 |  |  |  |  | }
343 |  |  |  |  |
344 | 1 | 16µs |  |  | 1;
345 |  |  |  |  |
346 |  |  |  |  | __END__
347 |  |  |  |  |
348 |  |  |  |  | =head1 NAME
349 |  |  |  |  |
350 |  |  |  |  | URI - 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 |  |  |  |  |
374 |  |  |  |  | This module implements the C<URI> class. Objects of this class
375 |  |  |  |  | represent "Uniform Resource Identifier references" as specified in RFC
376 |  |  |  |  | 2396 (and updated by RFC 2732).
377 |  |  |  |  |
378 |  |  |  |  | A Uniform Resource Identifier is a compact string of characters that
379 |  |  |  |  | identifies an abstract or physical resource. A Uniform Resource
380 |  |  |  |  | Identifier can be further classified as either a Uniform Resource Locator
381 |  |  |  |  | (URL) or a Uniform Resource Name (URN). The distinction between URL
382 |  |  |  |  | and URN does not matter to the C<URI> class interface. A
383 |  |  |  |  | "URI-reference" is a URI that may have additional information attached
384 |  |  |  |  | in the form of a fragment identifier.
385 |  |  |  |  |
386 |  |  |  |  | An absolute URI reference consists of three parts: a I<scheme>, a
387 |  |  |  |  | I<scheme-specific part> and a I<fragment> identifier. A subset of URI
388 |  |  |  |  | references share a common syntax for hierarchical namespaces. For
389 |  |  |  |  | these, the scheme-specific part is further broken down into
390 |  |  |  |  | I<authority>, I<path> and I<query> components. These URIs can also
391 |  |  |  |  | take the form of relative URI references, where the scheme (and
392 |  |  |  |  | usually also the authority) component is missing, but implied by the
393 |  |  |  |  | context of the URI reference. The three forms of URI reference
394 |  |  |  |  | syntax are summarized as follows:
395 |  |  |  |  |
396 |  |  |  |  | <scheme>:<scheme-specific-part>#<fragment>
397 |  |  |  |  | <scheme>://<authority><path>?<query>#<fragment>
398 |  |  |  |  | <path>?<query>#<fragment>
399 |  |  |  |  |
400 |  |  |  |  | The components into which a URI reference can be divided depend on the
401 |  |  |  |  | I<scheme>. The C<URI> class provides methods to get and set the
402 |  |  |  |  | individual components. The methods available for a specific
403 |  |  |  |  | C<URI> object depend on the scheme.
404 |  |  |  |  |
405 |  |  |  |  | =head1 CONSTRUCTORS
406 |  |  |  |  |
407 |  |  |  |  | The 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 |  |  |  |  |
415 |  |  |  |  | Constructs a new URI object. The string
416 |  |  |  |  | representation of a URI is given as argument, together with an optional
417 |  |  |  |  | scheme specification. Common URI wrappers like "" and <>, as well as
418 |  |  |  |  | leading and trailing white space, are automatically removed from
419 |  |  |  |  | the $str argument before it is processed further.
420 |  |  |  |  |
421 |  |  |  |  | The constructor determines the scheme, maps this to an appropriate
422 |  |  |  |  | URI subclass, constructs a new object of that class and returns it.
423 |  |  |  |  |
424 |  |  |  |  | The $scheme argument is only used when $str is a
425 |  |  |  |  | relative URI. It can be either a simple string that
426 |  |  |  |  | denotes the scheme, a string containing an absolute URI reference, or
427 |  |  |  |  | an absolute C<URI> object. If no $scheme is specified for a relative
428 |  |  |  |  | URI $str, then $str is simply treated as a generic URI (no scheme-specific
429 |  |  |  |  | methods available).
430 |  |  |  |  |
431 |  |  |  |  | The set of characters available for building URI references is
432 |  |  |  |  | restricted (see L<URI::Escape>). Characters outside this set are
433 |  |  |  |  | automatically escaped by the URI constructor.
434 |  |  |  |  |
435 |  |  |  |  | =item $uri = URI->new_abs( $str, $base_uri )
436 |  |  |  |  |
437 |  |  |  |  | Constructs a new absolute URI object. The $str argument can
438 |  |  |  |  | denote a relative or absolute URI. If relative, then it is
439 |  |  |  |  | absolutized using $base_uri as base. The $base_uri must be an absolute
440 |  |  |  |  | URI.
441 |  |  |  |  |
442 |  |  |  |  | =item $uri = URI::file->new( $filename )
443 |  |  |  |  |
444 |  |  |  |  | =item $uri = URI::file->new( $filename, $os )
445 |  |  |  |  |
446 |  |  |  |  | Constructs 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 |  |  |  |  |
452 |  |  |  |  | Constructs a new absolute I<file> URI from a file name. See
453 |  |  |  |  | L<URI::file>.
454 |  |  |  |  |
455 |  |  |  |  | =item $uri = URI::file->cwd
456 |  |  |  |  |
457 |  |  |  |  | Returns the current working directory as a I<file> URI. See
458 |  |  |  |  | L<URI::file>.
459 |  |  |  |  |
460 |  |  |  |  | =item $uri->clone
461 |  |  |  |  |
462 |  |  |  |  | Returns a copy of the $uri.
463 |  |  |  |  |
464 |  |  |  |  | =back
465 |  |  |  |  |
466 |  |  |  |  | =head1 COMMON METHODS
467 |  |  |  |  |
468 |  |  |  |  | The methods described in this section are available for all C<URI>
469 |  |  |  |  | objects.
470 |  |  |  |  |
471 |  |  |  |  | Methods that give access to components of a URI always return the
472 |  |  |  |  | old value of the component. The value returned is C<undef> if the
473 |  |  |  |  | component was not present. There is generally a difference between a
474 |  |  |  |  | component that is empty (represented as C<"">) and a component that is
475 |  |  |  |  | missing (represented as C<undef>). If an accessor method is given an
476 |  |  |  |  | argument, it updates the corresponding component in addition to
477 |  |  |  |  | returning the old value of the component. Passing an undefined
478 |  |  |  |  | argument removes the component (if possible). The description of
479 |  |  |  |  | each accessor method indicates whether the component is passed as
480 |  |  |  |  | an escaped or an unescaped string. A component that can be further
481 |  |  |  |  | divided into sub-parts are usually passed escaped, as unescaping might
482 |  |  |  |  | change its semantics.
483 |  |  |  |  |
484 |  |  |  |  | The common methods available for all URI are:
485 |  |  |  |  |
486 |  |  |  |  | =over 4
487 |  |  |  |  |
488 |  |  |  |  | =item $uri->scheme
489 |  |  |  |  |
490 |  |  |  |  | =item $uri->scheme( $new_scheme )
491 |  |  |  |  |
492 |  |  |  |  | Sets and returns the scheme part of the $uri. If the $uri is
493 |  |  |  |  | relative, then $uri->scheme returns C<undef>. If called with an
494 |  |  |  |  | argument, it updates the scheme of $uri, possibly changing the
495 |  |  |  |  | class of $uri, and returns the old scheme value. The method croaks
496 |  |  |  |  | if the new scheme name is illegal; a scheme name must begin with a
497 |  |  |  |  | letter and must consist of only US-ASCII letters, numbers, and a few
498 |  |  |  |  | special marks: ".", "+", "-". This restriction effectively means
499 |  |  |  |  | that the scheme must be passed unescaped. Passing an undefined
500 |  |  |  |  | argument to the scheme method makes the URI relative (if possible).
501 |  |  |  |  |
502 |  |  |  |  | Letter case does not matter for scheme names. The string
503 |  |  |  |  | returned by $uri->scheme is always lowercase. If you want the scheme
504 |  |  |  |  | just as it was written in the URI in its original case,
505 |  |  |  |  | you can use the $uri->_scheme method instead.
506 |  |  |  |  |
507 |  |  |  |  | =item $uri->opaque
508 |  |  |  |  |
509 |  |  |  |  | =item $uri->opaque( $new_opaque )
510 |  |  |  |  |
511 |  |  |  |  | Sets and returns the scheme-specific part of the $uri
512 |  |  |  |  | (everything between the scheme and the fragment)
513 |  |  |  |  | as an escaped string.
514 |  |  |  |  |
515 |  |  |  |  | =item $uri->path
516 |  |  |  |  |
517 |  |  |  |  | =item $uri->path( $new_path )
518 |  |  |  |  |
519 |  |  |  |  | Sets and returns the same value as $uri->opaque unless the URI
520 |  |  |  |  | supports the generic syntax for hierarchical namespaces.
521 |  |  |  |  | In that case the generic method is overridden to set and return
522 |  |  |  |  | the 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 |  |  |  |  |
528 |  |  |  |  | Returns the fragment identifier of a URI reference
529 |  |  |  |  | as an escaped string.
530 |  |  |  |  |
531 |  |  |  |  | =item $uri->as_string
532 |  |  |  |  |
533 |  |  |  |  | Returns a URI object to a plain ASCII string. URI objects are
534 |  |  |  |  | also converted to plain strings automatically by overloading. This
535 |  |  |  |  | means that $uri objects can be used as plain strings in most Perl
536 |  |  |  |  | constructs.
537 |  |  |  |  |
538 |  |  |  |  | =item $uri->as_iri
539 |  |  |  |  |
540 |  |  |  |  | Returns a Unicode string representing the URI. Escaped UTF-8 sequences
541 |  |  |  |  | representing non-ASCII characters are turned into their corresponding Unicode
542 |  |  |  |  | code point.
543 |  |  |  |  |
544 |  |  |  |  | =item $uri->canonical
545 |  |  |  |  |
546 |  |  |  |  | Returns a normalized version of the URI. The rules
547 |  |  |  |  | for normalization are scheme-dependent. They usually involve
548 |  |  |  |  | lowercasing the scheme and Internet host name components,
549 |  |  |  |  | removing the explicit port specification if it matches the default port,
550 |  |  |  |  | uppercasing all escape sequences, and unescaping octets that can be
551 |  |  |  |  | better represented as plain characters.
552 |  |  |  |  |
553 |  |  |  |  | For efficiency reasons, if the $uri is already in normalized form,
554 |  |  |  |  | then 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 |  |  |  |  |
560 |  |  |  |  | Tests whether two URI references are equal. URI references
561 |  |  |  |  | that normalize to the same string are considered equal. The method
562 |  |  |  |  | can also be used as a plain function which can also test two string
563 |  |  |  |  | arguments.
564 |  |  |  |  |
565 |  |  |  |  | If you need to test whether two C<URI> object references denote the
566 |  |  |  |  | same object, use the '==' operator.
567 |  |  |  |  |
568 |  |  |  |  | =item $uri->abs( $base_uri )
569 |  |  |  |  |
570 |  |  |  |  | Returns an absolute URI reference. If $uri is already
571 |  |  |  |  | absolute, then a reference to it is simply returned. If the $uri
572 |  |  |  |  | is 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 |  |  |  |  |
577 |  |  |  |  | Returns a relative URI reference if it is possible to
578 |  |  |  |  | make one that denotes the same resource relative to $base_uri.
579 |  |  |  |  | If not, then $uri is simply returned.
580 |  |  |  |  |
581 |  |  |  |  | =back
582 |  |  |  |  |
583 |  |  |  |  | =head1 GENERIC METHODS
584 |  |  |  |  |
585 |  |  |  |  | The following methods are available to schemes that use the
586 |  |  |  |  | common/generic syntax for hierarchical namespaces. The descriptions of
587 |  |  |  |  | schemes below indicate which these are. Unknown schemes are
588 |  |  |  |  | assumed to support the generic syntax, and therefore the following
589 |  |  |  |  | methods:
590 |  |  |  |  |
591 |  |  |  |  | =over 4
592 |  |  |  |  |
593 |  |  |  |  | =item $uri->authority
594 |  |  |  |  |
595 |  |  |  |  | =item $uri->authority( $new_authority )
596 |  |  |  |  |
597 |  |  |  |  | Sets and returns the escaped authority component
598 |  |  |  |  | of the $uri.
599 |  |  |  |  |
600 |  |  |  |  | =item $uri->path
601 |  |  |  |  |
602 |  |  |  |  | =item $uri->path( $new_path )
603 |  |  |  |  |
604 |  |  |  |  | Sets and returns the escaped path component of
605 |  |  |  |  | the $uri (the part between the host name and the query or fragment).
606 |  |  |  |  | The 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 |  |  |  |  |
612 |  |  |  |  | Sets and returns the escaped path and query
613 |  |  |  |  | components as a single entity. The path and the query are
614 |  |  |  |  | separated by a "?" character, but the query can itself contain "?".
615 |  |  |  |  |
616 |  |  |  |  | =item $uri->path_segments
617 |  |  |  |  |
618 |  |  |  |  | =item $uri->path_segments( $segment, ... )
619 |  |  |  |  |
620 |  |  |  |  | Sets and returns the path. In a scalar context, it returns
621 |  |  |  |  | the same value as $uri->path. In a list context, it returns the
622 |  |  |  |  | unescaped path segments that make up the path. Path segments that
623 |  |  |  |  | have parameters are returned as an anonymous array. The first element
624 |  |  |  |  | is the unescaped path segment proper; subsequent elements are escaped
625 |  |  |  |  | parameter strings. Such an anonymous array uses overloading so it can
626 |  |  |  |  | be treated as a string too, but this string does not include the
627 |  |  |  |  | parameters.
628 |  |  |  |  |
629 |  |  |  |  | Note that absolute paths have the empty string as their first
630 |  |  |  |  | I<path_segment>, i.e. the I<path> C</foo/bar> have 3
631 |  |  |  |  | I<path_segments>; "", "foo" and "bar".
632 |  |  |  |  |
633 |  |  |  |  | =item $uri->query
634 |  |  |  |  |
635 |  |  |  |  | =item $uri->query( $new_query )
636 |  |  |  |  |
637 |  |  |  |  | Sets and returns the escaped query component of
638 |  |  |  |  | the $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 |  |  |  |  |
654 |  |  |  |  | Sets and returns query components that use the
655 |  |  |  |  | I<application/x-www-form-urlencoded> format. Key/value pairs are
656 |  |  |  |  | separated by "&", and the key is separated from the value by a "="
657 |  |  |  |  | character.
658 |  |  |  |  |
659 |  |  |  |  | The form can be set either by passing separate key/value pairs, or via
660 |  |  |  |  | an array or hash reference. Passing an empty array or an empty hash
661 |  |  |  |  | removes the query component, whereas passing no arguments at all leaves
662 |  |  |  |  | the component unchanged. The order of keys is undefined if a hash
663 |  |  |  |  | reference is passed. The old value is always returned as a list of
664 |  |  |  |  | separate key/value pairs. Assigning this list to a hash is unwise as
665 |  |  |  |  | the keys returned might repeat.
666 |  |  |  |  |
667 |  |  |  |  | The values passed when setting the form can be plain strings or
668 |  |  |  |  | references to arrays of strings. Passing an array of values has the
669 |  |  |  |  | same effect as passing the key repeatedly with one value at a time.
670 |  |  |  |  | All 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 |  |  |  |  |
678 |  |  |  |  | The $delim parameter can be passed as ";" to force the key/value pairs
679 |  |  |  |  | to be delimited by ";" instead of "&" in the query string. This
680 |  |  |  |  | practice is often recommended for URLs embedded in HTML or XML
681 |  |  |  |  | documents as this avoids the trouble of escaping the "&" character.
682 |  |  |  |  | You might also set the $URI::DEFAULT_QUERY_FORM_DELIMITER variable to
683 |  |  |  |  | ";" for the same global effect.
684 |  |  |  |  |
685 |  |  |  |  | The C<URI::QueryParam> module can be loaded to add further methods to
686 |  |  |  |  | manipulate 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 |  |  |  |  |
694 |  |  |  |  | Sets and returns query components that use the
695 |  |  |  |  | keywords separated by "+" format.
696 |  |  |  |  |
697 |  |  |  |  | The keywords can be set either by passing separate keywords directly
698 |  |  |  |  | or by passing a reference to an array of keywords. Passing an empty
699 |  |  |  |  | array removes the query component, whereas passing no arguments at
700 |  |  |  |  | all leaves the component unchanged. The old value is always returned
701 |  |  |  |  | as a list of separate words.
702 |  |  |  |  |
703 |  |  |  |  | =back
704 |  |  |  |  |
705 |  |  |  |  | =head1 SERVER METHODS
706 |  |  |  |  |
707 |  |  |  |  | For schemes where the I<authority> component denotes an Internet host,
708 |  |  |  |  | the following methods are available in addition to the generic
709 |  |  |  |  | methods.
710 |  |  |  |  |
711 |  |  |  |  | =over 4
712 |  |  |  |  |
713 |  |  |  |  | =item $uri->userinfo
714 |  |  |  |  |
715 |  |  |  |  | =item $uri->userinfo( $new_userinfo )
716 |  |  |  |  |
717 |  |  |  |  | Sets and returns the escaped userinfo part of the
718 |  |  |  |  | authority component.
719 |  |  |  |  |
720 |  |  |  |  | For some schemes this is a user name and a password separated by
721 |  |  |  |  | a colon. This practice is not recommended. Embedding passwords in
722 |  |  |  |  | clear text (such as URI) has proven to be a security risk in almost
723 |  |  |  |  | every case where it has been used.
724 |  |  |  |  |
725 |  |  |  |  | =item $uri->host
726 |  |  |  |  |
727 |  |  |  |  | =item $uri->host( $new_host )
728 |  |  |  |  |
729 |  |  |  |  | Sets and returns the unescaped hostname.
730 |  |  |  |  |
731 |  |  |  |  | If the $new_host string ends with a colon and a number, then this
732 |  |  |  |  | number also sets the port.
733 |  |  |  |  |
734 |  |  |  |  | For IPv6 addresses the brackets around the raw address is removed in the return
735 |  |  |  |  | value from $uri->host. When setting the host attribute to an IPv6 address you
736 |  |  |  |  | can use a raw address or one enclosed in brackets. The address needs to be
737 |  |  |  |  | enclosed in brackets if you want to pass in a new port value as well.
738 |  |  |  |  |
739 |  |  |  |  | =item $uri->ihost
740 |  |  |  |  |
741 |  |  |  |  | Returns 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 |  |  |  |  |
747 |  |  |  |  | Sets and returns the port. The port is a simple integer
748 |  |  |  |  | that should be greater than 0.
749 |  |  |  |  |
750 |  |  |  |  | If a port is not specified explicitly in the URI, then the URI scheme's default port
751 |  |  |  |  | is returned. If you don't want the default port
752 |  |  |  |  | substituted, 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 |  |  |  |  |
758 |  |  |  |  | Sets and returns the host and port as a single
759 |  |  |  |  | unit. The returned value includes a port, even if it matches the
760 |  |  |  |  | default port. The host part and the port part are separated by a
761 |  |  |  |  | colon: ":".
762 |  |  |  |  |
763 |  |  |  |  | For IPv6 addresses the bracketing is preserved; thus
764 |  |  |  |  | URI->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 |  |  |  |  |
769 |  |  |  |  | Returns the default port of the URI scheme to which $uri
770 |  |  |  |  | belongs. For I<http> this is the number 80, for I<ftp> this
771 |  |  |  |  | is the number 21, etc. The default port for a scheme can not be
772 |  |  |  |  | changed.
773 |  |  |  |  |
774 |  |  |  |  | =back
775 |  |  |  |  |
776 |  |  |  |  | =head1 SCHEME-SPECIFIC SUPPORT
777 |  |  |  |  |
778 |  |  |  |  | Scheme-specific support is provided for the following URI schemes. For C<URI>
779 |  |  |  |  | objects that do not belong to one of these, you can only use the common and
780 |  |  |  |  | generic methods.
781 |  |  |  |  |
782 |  |  |  |  | =over 4
783 |  |  |  |  |
784 |  |  |  |  | =item B<data>:
785 |  |  |  |  |
786 |  |  |  |  | The I<data> URI scheme is specified in RFC 2397. It allows inclusion
787 |  |  |  |  | of small data items as "immediate" data, as if it had been included
788 |  |  |  |  | externally.
789 |  |  |  |  |
790 |  |  |  |  | C<URI> objects belonging to the data scheme support the common methods
791 |  |  |  |  | and 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 |  |  |  |  |
796 |  |  |  |  | An old specification of the I<file> URI scheme is found in RFC 1738.
797 |  |  |  |  | A new RFC 2396 based specification in not available yet, but file URI
798 |  |  |  |  | references are in common use.
799 |  |  |  |  |
800 |  |  |  |  | C<URI> objects belonging to the file scheme support the common and
801 |  |  |  |  | generic methods. In addition, they provide two methods for mapping file URIs
802 |  |  |  |  | back to local file names; $uri->file and $uri->dir. See L<URI::file>
803 |  |  |  |  | for details.
804 |  |  |  |  |
805 |  |  |  |  | =item B<ftp>:
806 |  |  |  |  |
807 |  |  |  |  | An old specification of the I<ftp> URI scheme is found in RFC 1738. A
808 |  |  |  |  | new RFC 2396 based specification in not available yet, but ftp URI
809 |  |  |  |  | references are in common use.
810 |  |  |  |  |
811 |  |  |  |  | C<URI> objects belonging to the ftp scheme support the common,
812 |  |  |  |  | generic and server methods. In addition, they provide two methods for
813 |  |  |  |  | accessing the userinfo sub-components: $uri->user and $uri->password.
814 |  |  |  |  |
815 |  |  |  |  | =item B<gopher>:
816 |  |  |  |  |
817 |  |  |  |  | The I<gopher> URI scheme is specified in
818 |  |  |  |  | <draft-murali-url-gopher-1996-12-04> and will hopefully be available
819 |  |  |  |  | as a RFC 2396 based specification.
820 |  |  |  |  |
821 |  |  |  |  | C<URI> objects belonging to the gopher scheme support the common,
822 |  |  |  |  | generic and server methods. In addition, they support some methods for
823 |  |  |  |  | accessing gopher-specific path components: $uri->gopher_type,
824 |  |  |  |  | $uri->selector, $uri->search, $uri->string.
825 |  |  |  |  |
826 |  |  |  |  | =item B<http>:
827 |  |  |  |  |
828 |  |  |  |  | The I<http> URI scheme is specified in RFC 2616.
829 |  |  |  |  | The scheme is used to reference resources hosted by HTTP servers.
830 |  |  |  |  |
831 |  |  |  |  | C<URI> objects belonging to the http scheme support the common,
832 |  |  |  |  | generic and server methods.
833 |  |  |  |  |
834 |  |  |  |  | =item B<https>:
835 |  |  |  |  |
836 |  |  |  |  | The I<https> URI scheme is a Netscape invention which is commonly
837 |  |  |  |  | implemented. The scheme is used to reference HTTP servers through SSL
838 |  |  |  |  | connections. Its syntax is the same as http, but the default
839 |  |  |  |  | port is different.
840 |  |  |  |  |
841 |  |  |  |  | =item B<ldap>:
842 |  |  |  |  |
843 |  |  |  |  | The I<ldap> URI scheme is specified in RFC 2255. LDAP is the
844 |  |  |  |  | Lightweight Directory Access Protocol. An ldap URI describes an LDAP
845 |  |  |  |  | search operation to perform to retrieve information from an LDAP
846 |  |  |  |  | directory.
847 |  |  |  |  |
848 |  |  |  |  | C<URI> objects belonging to the ldap scheme support the common,
849 |  |  |  |  | generic and server methods as well as ldap-specific methods: $uri->dn,
850 |  |  |  |  | $uri->attributes, $uri->scope, $uri->filter, $uri->extensions. See
851 |  |  |  |  | L<URI::ldap> for details.
852 |  |  |  |  |
853 |  |  |  |  | =item B<ldapi>:
854 |  |  |  |  |
855 |  |  |  |  | Like the I<ldap> URI scheme, but uses a UNIX domain socket. The
856 |  |  |  |  | server methods are not supported, and the local socket path is
857 |  |  |  |  | available as $uri->un_path. The I<ldapi> scheme is used by the
858 |  |  |  |  | OpenLDAP package. There is no real specification for it, but it is
859 |  |  |  |  | mentioned in various OpenLDAP manual pages.
860 |  |  |  |  |
861 |  |  |  |  | =item B<ldaps>:
862 |  |  |  |  |
863 |  |  |  |  | Like the I<ldap> URI scheme, but uses an SSL connection. This
864 |  |  |  |  | scheme is deprecated, as the preferred way is to use the I<start_tls>
865 |  |  |  |  | mechanism.
866 |  |  |  |  |
867 |  |  |  |  | =item B<mailto>:
868 |  |  |  |  |
869 |  |  |  |  | The I<mailto> URI scheme is specified in RFC 2368. The scheme was
870 |  |  |  |  | originally used to designate the Internet mailing address of an
871 |  |  |  |  | individual or service. It has (in RFC 2368) been extended to allow
872 |  |  |  |  | setting of other mail header fields and the message body.
873 |  |  |  |  |
874 |  |  |  |  | C<URI> objects belonging to the mailto scheme support the common
875 |  |  |  |  | methods and the generic query methods. In addition, they support the
876 |  |  |  |  | following mailto-specific methods: $uri->to, $uri->headers.
877 |  |  |  |  |
878 |  |  |  |  | Note that the "foo@example.com" part of a mailto is I<not> the
879 |  |  |  |  | C<userinfo> and C<host> but instead the C<path>. This allowed a
880 |  |  |  |  | mailto to contain multiple comma-seperated email addresses.
881 |  |  |  |  |
882 |  |  |  |  | =item B<mms>:
883 |  |  |  |  |
884 |  |  |  |  | The I<mms> URL specification can be found at L<http://sdp.ppona.com/>
885 |  |  |  |  | C<URI> objects belonging to the mms scheme support the common,
886 |  |  |  |  | generic, and server methods, with the exception of userinfo and
887 |  |  |  |  | query-related sub-components.
888 |  |  |  |  |
889 |  |  |  |  | =item B<news>:
890 |  |  |  |  |
891 |  |  |  |  | The 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
893 |  |  |  |  | 2396 based specification soon.
894 |  |  |  |  |
895 |  |  |  |  | C<URI> objects belonging to the news scheme support the common,
896 |  |  |  |  | generic and server methods. In addition, they provide some methods to
897 |  |  |  |  | access the path: $uri->group and $uri->message.
898 |  |  |  |  |
899 |  |  |  |  | =item B<nntp>:
900 |  |  |  |  |
901 |  |  |  |  | See I<news> scheme.
902 |  |  |  |  |
903 |  |  |  |  | =item B<pop>:
904 |  |  |  |  |
905 |  |  |  |  | The I<pop> URI scheme is specified in RFC 2384. The scheme is used to
906 |  |  |  |  | reference a POP3 mailbox.
907 |  |  |  |  |
908 |  |  |  |  | C<URI> objects belonging to the pop scheme support the common, generic
909 |  |  |  |  | and server methods. In addition, they provide two methods to access the
910 |  |  |  |  | userinfo components: $uri->user and $uri->auth
911 |  |  |  |  |
912 |  |  |  |  | =item B<rlogin>:
913 |  |  |  |  |
914 |  |  |  |  | An old specification of the I<rlogin> URI scheme is found in RFC
915 |  |  |  |  | 1738. C<URI> objects belonging to the rlogin scheme support the
916 |  |  |  |  | common, generic and server methods.
917 |  |  |  |  |
918 |  |  |  |  | =item B<rtsp>:
919 |  |  |  |  |
920 |  |  |  |  | The I<rtsp> URL specification can be found in section 3.2 of RFC 2326.
921 |  |  |  |  | C<URI> objects belonging to the rtsp scheme support the common,
922 |  |  |  |  | generic, and server methods, with the exception of userinfo and
923 |  |  |  |  | query-related sub-components.
924 |  |  |  |  |
925 |  |  |  |  | =item B<rtspu>:
926 |  |  |  |  |
927 |  |  |  |  | The I<rtspu> URI scheme is used to talk to RTSP servers over UDP
928 |  |  |  |  | instead of TCP. The syntax is the same as rtsp.
929 |  |  |  |  |
930 |  |  |  |  | =item B<rsync>:
931 |  |  |  |  |
932 |  |  |  |  | Information about rsync is available from http://rsync.samba.org.
933 |  |  |  |  | C<URI> objects belonging to the rsync scheme support the common,
934 |  |  |  |  | generic and server methods. In addition, they provide methods to
935 |  |  |  |  | access the userinfo sub-components: $uri->user and $uri->password.
936 |  |  |  |  |
937 |  |  |  |  | =item B<sip>:
938 |  |  |  |  |
939 |  |  |  |  | The I<sip> URI specification is described in sections 19.1 and 25
940 |  |  |  |  | of RFC 3261. C<URI> objects belonging to the sip scheme support the
941 |  |  |  |  | common, generic, and server methods with the exception of path related
942 |  |  |  |  | sub-components. In addition, they provide two methods to get and set
943 |  |  |  |  | I<sip> parameters: $uri->params_form and $uri->params.
944 |  |  |  |  |
945 |  |  |  |  | =item B<sips>:
946 |  |  |  |  |
947 |  |  |  |  | See I<sip> scheme. Its syntax is the same as sip, but the default
948 |  |  |  |  | port is different.
949 |  |  |  |  |
950 |  |  |  |  | =item B<snews>:
951 |  |  |  |  |
952 |  |  |  |  | See I<news> scheme. Its syntax is the same as news, but the default
953 |  |  |  |  | port is different.
954 |  |  |  |  |
955 |  |  |  |  | =item B<telnet>:
956 |  |  |  |  |
957 |  |  |  |  | An old specification of the I<telnet> URI scheme is found in RFC
958 |  |  |  |  | 1738. C<URI> objects belonging to the telnet scheme support the
959 |  |  |  |  | common, generic and server methods.
960 |  |  |  |  |
961 |  |  |  |  | =item B<tn3270>:
962 |  |  |  |  |
963 |  |  |  |  | These URIs are used like I<telnet> URIs but for connections to IBM
964 |  |  |  |  | mainframes. C<URI> objects belonging to the tn3270 scheme support the
965 |  |  |  |  | common, generic and server methods.
966 |  |  |  |  |
967 |  |  |  |  | =item B<ssh>:
968 |  |  |  |  |
969 |  |  |  |  | Information about ssh is available at http://www.openssh.com/.
970 |  |  |  |  | C<URI> objects belonging to the ssh scheme support the common,
971 |  |  |  |  | generic and server methods. In addition, they provide methods to
972 |  |  |  |  | access the userinfo sub-components: $uri->user and $uri->password.
973 |  |  |  |  |
974 |  |  |  |  | =item B<urn>:
975 |  |  |  |  |
976 |  |  |  |  | The syntax of Uniform Resource Names is specified in RFC 2141. C<URI>
977 |  |  |  |  | objects belonging to the urn scheme provide the common methods, and also the
978 |  |  |  |  | methods $uri->nid and $uri->nss, which return the Namespace Identifier
979 |  |  |  |  | and the Namespace-Specific String respectively.
980 |  |  |  |  |
981 |  |  |  |  | The Namespace Identifier basically works like the Scheme identifier of
982 |  |  |  |  | URIs, and further divides the URN namespace. Namespace Identifier
983 |  |  |  |  | assignments are maintained at
984 |  |  |  |  | <http://www.iana.org/assignments/urn-namespaces>.
985 |  |  |  |  |
986 |  |  |  |  | Letter case is not significant for the Namespace Identifier. It is
987 |  |  |  |  | always returned in lower case by the $uri->nid method. The $uri->_nid
988 |  |  |  |  | method can be used if you want it in its original case.
989 |  |  |  |  |
990 |  |  |  |  | =item B<urn>:B<isbn>:
991 |  |  |  |  |
992 |  |  |  |  | The C<urn:isbn:> namespace contains International Standard Book
993 |  |  |  |  | Numbers (ISBNs) and is described in RFC 3187. A C<URI> object belonging
994 |  |  |  |  | to this namespace has the following extra methods (if the
995 |  |  |  |  | Business::ISBN module is available): $uri->isbn,
996 |  |  |  |  | $uri->isbn_publisher_code, $uri->isbn_group_code (formerly isbn_country_code,
997 |  |  |  |  | which is still supported by issues a deprecation warning), $uri->isbn_as_ean.
998 |  |  |  |  |
999 |  |  |  |  | =item B<urn>:B<oid>:
1000 |  |  |  |  |
1001 |  |  |  |  | The C<urn:oid:> namespace contains Object Identifiers (OIDs) and is
1002 |  |  |  |  | described in RFC 3061. An object identifier consists of sequences of digits
1003 |  |  |  |  | separated by dots. A C<URI> object belonging to this namespace has an
1004 |  |  |  |  | additional method called $uri->oid that can be used to get/set the oid
1005 |  |  |  |  | value. In a list context, oid numbers are returned as separate elements.
1006 |  |  |  |  |
1007 |  |  |  |  | =back
1008 |  |  |  |  |
1009 |  |  |  |  | =head1 CONFIGURATION VARIABLES
1010 |  |  |  |  |
1011 |  |  |  |  | The following configuration variables influence how the class and its
1012 |  |  |  |  | methods behave:
1013 |  |  |  |  |
1014 |  |  |  |  | =over 4
1015 |  |  |  |  |
1016 |  |  |  |  | =item $URI::ABS_ALLOW_RELATIVE_SCHEME
1017 |  |  |  |  |
1018 |  |  |  |  | Some older parsers used to allow the scheme name to be present in the
1019 |  |  |  |  | relative URL if it was the same as the base URL scheme. RFC 2396 says
1020 |  |  |  |  | that this should be avoided, but you can enable this old behaviour by
1021 |  |  |  |  | setting the $URI::ABS_ALLOW_RELATIVE_SCHEME variable to a TRUE value.
1022 |  |  |  |  | The 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 |  |  |  |  |
1034 |  |  |  |  | You can also have the abs() method ignore excess ".."
1035 |  |  |  |  | segments in the relative URI by setting $URI::ABS_REMOTE_LEADING_DOTS
1036 |  |  |  |  | to a TRUE value. The difference is demonstrated by the following
1037 |  |  |  |  | examples:
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 |  |  |  |  |
1048 |  |  |  |  | This value can be set to ";" to have the query form C<key=value> pairs
1049 |  |  |  |  | delimited by ";" instead of "&" which is the default.
1050 |  |  |  |  |
1051 |  |  |  |  | =back
1052 |  |  |  |  |
1053 |  |  |  |  | =head1 BUGS
1054 |  |  |  |  |
1055 |  |  |  |  | Using regexp variables like $1 directly as arguments to the URI methods
1056 |  |  |  |  | does not work too well with current perl implementations. I would argue
1057 |  |  |  |  | that this is actually a bug in perl. The workaround is to quote
1058 |  |  |  |  | them. Example:
1059 |  |  |  |  |
1060 |  |  |  |  | /(...)/ || die;
1061 |  |  |  |  | $u->query("$1");
1062 |  |  |  |  |
1063 |  |  |  |  | =head1 PARSING URIs WITH REGEXP
1064 |  |  |  |  |
1065 |  |  |  |  | As an alternative to this module, the following (official) regular
1066 |  |  |  |  | expression can be used to decode a URI:
1067 |  |  |  |  |
1068 |  |  |  |  | my($scheme, $authority, $path, $query, $fragment) =
1069 |  |  |  |  | $uri =~ m|(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?|;
1070 |  |  |  |  |
1071 |  |  |  |  | The C<URI::Split> module provides the function uri_split() as a
1072 |  |  |  |  | readable alternative.
1073 |  |  |  |  |
1074 |  |  |  |  | =head1 SEE ALSO
1075 |  |  |  |  |
1076 |  |  |  |  | L<URI::file>, L<URI::WithBase>, L<URI::QueryParam>, L<URI::Escape>,
1077 |  |  |  |  | L<URI::Split>, L<URI::Heuristic>
1078 |  |  |  |  |
1079 |  |  |  |  | RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax",
1080 |  |  |  |  | Berners-Lee, Fielding, Masinter, August 1998.
1081 |  |  |  |  |
1082 |  |  |  |  | http://www.iana.org/assignments/uri-schemes
1083 |  |  |  |  |
1084 |  |  |  |  | http://www.iana.org/assignments/urn-namespaces
1085 |  |  |  |  |
1086 |  |  |  |  | http://www.w3.org/Addressing/
1087 |  |  |  |  |
1088 |  |  |  |  | =head1 COPYRIGHT
1089 |  |  |  |  |
1090 |  |  |  |  | Copyright 1995-2009 Gisle Aas.
1091 |  |  |  |  |
1092 |  |  |  |  | Copyright 1995 Martijn Koster.
1093 |  |  |  |  |
1094 |  |  |  |  | This program is free software; you can redistribute it and/or modify
1095 |  |  |  |  | it under the same terms as Perl itself.
1096 |  |  |  |  |
1097 |  |  |  |  | =head1 AUTHORS / ACKNOWLEDGMENTS
1098 |  |  |  |  |
1099 |  |  |  |  | This 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
1101 |  |  |  |  | perl4 developed by Roy Fielding, as part of the Arcadia project at the
1102 |  |  |  |  | University of California, Irvine, with contributions from Brooks
1103 |  |  |  |  | Cutter.
1104 |  |  |  |  |
1105 |  |  |  |  | C<URI::URL> was developed by Gisle Aas, Tim Bunce, Roy Fielding and
1106 |  |  |  |  | Martijn Koster with input from other people on the libwww-perl mailing
1107 |  |  |  |  | list.
1108 |  |  |  |  |
1109 |  |  |  |  | C<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