APR::URI(3pm)

1docs::api::APR::URI(3)User Contributed Perl Documentationdocs::api::APR::URI(3)
2
3
4

NAME

6       APR::URI - Perl API for URI manipulations
7

Synopsis

9         use APR::URI ();
10
11         my $url = 'http://user:pass@example.com:80/foo?bar#item5';
12
13         # parse and break the url into components
14         my $parsed = APR::URI->parse($r->pool, $url);
15         print $parsed->scheme;
16         print $parsed->user;
17         print $parsed->password;
18         print $parsed->hostname;
19         print $parsed->port;
20         print $parsed->path;
21         print $parsed->rpath;
22         print $parsed->query;
23         print $parsed->fragment;
24
25         # reconstruct the url, after changing some components and completely
26         # removing other
27         $parsed->scheme($new_scheme);
28         $parsed->user(undef);
29         $parsed->password(undef);
30         $parsed->hostname($new_hostname);
31         $parsed->port($new_port);
32         $parsed->path($new_path);
33         $parsed->query(undef);
34         $parsed->fragment(undef);
35         print $parsed->unparse;
36
37         # get the password field too (by default it's not revealed)
38         use APR::Const -compile => qw(URI_UNP_REVEALPASSWORD);
39         print $parsed->unparse(APR::Const::URI_UNP_REVEALPASSWORD);
40
41         # what the default port for the ftp protocol?
42         my $ftp_port = APR::URI::port_of_scheme("ftp");
43

Description

45       "APR::URI" allows you to parse URI strings, manipulate each of the URI
46       elements and deparse them back into URIs.
47
48       All "APR::URI" object accessors accept a string or an "undef" value as
49       an argument. Same goes for return value. It's important to distinguish
50       between an empty string and "undef". For example let's say your code
51       was:
52
53         my $uri = 'http://example.com/foo?bar#item5';
54         my $parsed = APR::URI->parse($r->pool, $uri);
55
56       Now you no longer want to the query and fragment components in the
57       final url. If you do:
58
59         $parsed->fragment('');
60         $parsed->query('');
61
62       followed by:
63
64         my $new_uri = parsed->unparse;
65
66       the resulting URI will be:
67
68         http://example.com/foo?#
69
70       which is probably not something that you've expected. In order to get
71       rid of the separators, you must completely unset the fields you don't
72       want to see. So, if you do:
73
74         $parsed->fragment(undef);
75         $parsed->query(undef);
76
77       followed by:
78
79         my $new_uri = parsed->unparse;
80
81       the resulting URI will be:
82
83          http://example.com/foo
84
85       As mentioned earlier the same goes for return values, so continuing
86       this example:
87
88         my $new_fragment = $parsed->fragment();
89         my $new_query    = $parsed->query();
90
91       Both values now contain "undef", therefore you must be careful when
92       using the return values, when you use them, as you may get warnings.
93
94       Also make sure you read through "the unparse() section" as various
95       optional flags affect how the deparsed URI is rendered.
96

API

98       "APR::URI" provides the following functions and/or methods:
99
100       "fragment"
101
102       Get/set trailing "#fragment" string
103
104         $oldval = $parsed->fragment($newval);
105
106       obj: $parsed ( "APR::URI object" )
107       opt arg1: $newval ( string or undef )
108       ret: $oldval ( string or undef )
109       since: 2.0.00
110
111       "hostinfo"
112
113       Get/set combined "[user[:password]@]host[:port]"
114
115         $oldval = $parsed->hostinfo($newval);
116
117       obj: $parsed ( "APR::URI object" )
118       opt arg1: $newval ( string or undef )
119       ret: $oldval ( string or undef )
120       since: 2.0.00
121
122       The "hostinfo" value is set automatically when "parse()" is called.
123
124       It's not updated if any of the individual fields is modified.
125
126       It's not used when "unparse()" is called.
127
128       "hostname"
129
130       Get/set hostname
131
132         $oldval = $parsed->hostname($newval);
133
134       obj: $parsed ( "APR::URI object" )
135       opt arg1: $newval ( string or undef )
136       ret: $oldval ( string or undef )
137       since: 2.0.00
138
139       "password"
140
141       Get/set password (as in http://user:password@host:port/)
142
143         $oldval = $parsed->password($newval);
144
145       obj: $parsed ( "APR::URI object" )
146       opt arg1: $newval ( string or undef )
147       ret: $oldval ( string or undef )
148       since: 2.0.00
149
150       "parse"
151
152       Parse the URI string into URI components
153
154         $parsed = APR::URI->parse($pool, $uri);
155
156       obj: $parsed ( "APR::URI object or class" )
157       arg1: $pool ( string ) ( "APR::Pool object" )
158       arg2: $uri ( string )
159           The URI to parse
160
161       ret: $parsed ( "APR::URI object or class" )
162           The parsed URI object
163
164       since: 2.0.00
165
166       After parsing, if a component existed but was an empty string (e.g.
167       empty query http://hostname/path?) -- the corresponding accessor will
168       return an empty string. If a component didn't exist (e.g. no query part
169       http://hostname/path) -- the corresponding accessor will return
170       "undef".
171
172       "path"
173
174       Get/set the request path
175
176         $oldval = $parsed->path($newval);
177
178       obj: $parsed ( "APR::URI object" )
179       opt arg1: $newval ( string or undef )
180       ret: $oldval ( string or undef )
181           "/" if only "scheme://host"
182
183       since: 2.0.00
184
185       "rpath"
186
187       Gets the "path" minus the "path_info"
188
189         $rpath =  $parsed->rpath();
190
191       obj: $parsed ( "APR::URI object" )
192       opt arg1: $newval ( string or undef )
193       ret: $oldval ( string or undef )
194           The path minus the path_info
195
196       since: 2.0.00
197
198       "port"
199
200       Get/set port number
201
202         $oldval = $parsed->port($newval);
203
204       obj: $parsed ( "APR::URI object" )
205       opt arg1: $newval ( number or string or undef )
206       ret: $oldval ( string or undef )
207           If the port component didn't appear in the parsed URI, APR inter‐
208           nally calls "port_of_scheme()" to find out the port number for the
209           given "scheme()".
210
211       since: 2.0.00
212
213       "port_of_scheme"
214
215       Return the default port for a given scheme.  The recognized schemes are
216       http, ftp, https, gopher, wais, nntp, snews and prospero.
217
218         $port = APR::URI::port_of_scheme($scheme);
219
220       obj: $scheme ( string )
221           The scheme string
222
223       ret: $port (integer)
224           The default port for this scheme
225
226       since: 2.0.00
227
228       "query"
229
230       Get/set the query string (the part starting after '?' and all the way
231       till the end or the '#fragment' part if the latter exists).
232
233         $oldval = $parsed->query($newval);
234
235       obj: $parsed ( "APR::URI object" )
236       opt arg1: $newval ( string or undef )
237       ret: $oldval ( string or undef )
238       since: 2.0.00
239
240       "scheme"
241
242       Get/set the protocol scheme ("http", "ftp", ...)
243
244         $oldval = $parsed->scheme($newval);
245
246       obj: $parsed ( "APR::URI object" )
247       opt arg1: $newval ( string or undef )
248       ret: $oldval ( string or undef )
249       since: 2.0.00
250
251       "user"
252
253       Get/set user name (as in http://user:password@host:port/)
254
255         $oldval = $parsed->user($newval);
256
257       obj: $parsed ( "APR::URI object" )
258       opt arg1: $newval ( string or undef )
259       ret: $oldval ( string or undef )
260       since: 2.0.00
261
262       "unparse"
263
264       Unparse the URI components back into a URI string
265
266         $new_uri = $parsed->unparse();
267         $new_uri = $parsed->unparse($flags);
268
269       obj: $parsed ( "APR::URI object" )
270       opt arg1: $flags ( the APR::Const :uri constants )
271           By default the constant "APR::Const::URI_UNP_OMITPASSWORD" is
272           passed.
273
274           If you need to pass more than one flag use unary "⎪", e.g.:
275
276             $flags = APR::Const::URI_UNP_OMITUSER⎪APR::Const::URI_UNP_OMITPASSWORD;
277
278           The valid "flags" constants are listed next
279
280       ret: $new_uri ( string )
281       since: 2.0.00
282
283       Valid "flags" constants:
284
285       To import all URI constants you could do:
286
287         use APR::Const -compile => qw(:uri);
288
289       but there is a significant amount of them, most irrelevant to this
290       method. Therefore you probably don't want to do that. Instead specify
291       explicitly the ones that you need. All the relevant to this method con‐
292       stants start with "APR::URI_UNP_".
293
294       And the available constants are:
295
296       "APR::Const::URI_UNP_OMITSITEPART"
297           Don't show "scheme", "user", "password", "hostname" and "port" com‐
298           ponents (i.e. if you want only the relative URI)
299
300       "APR::Const::URI_UNP_OMITUSER"
301           Hide the "user" component
302
303       "APR::Const::URI_UNP_OMITPASSWORD"
304           Hide the "password" component (the default)
305
306       "APR::Const::URI_UNP_REVEALPASSWORD"
307           Reveal the "password" component
308
309       "APR::Const::URI_UNP_OMITPATHINFO"
310           Don't show "path", "query" and "fragment" components
311
312       "APR::Const::URI_UNP_OMITQUERY"
313           Don't show "query" and "fragment" components
314
315       Notice that some flags overlap.
316
317       If the optional $flags argument is passed and contains no
318       "APR::Const::URI_UNP_OMITPASSWORD" and no "APR::Const::URI_UNP_REVEAL‐
319       PASSWORD" -- the "password" part will be rendered as a literal
320       "XXXXXXXX" string.
321
322       If the "port" number matches the "port_of_scheme()", the unparsed URI
323       won't include it and there is no flag to force that "port" to appear.
324       If the "port" number is non-standard it will show up in the unparsed
325       string.
326
327       Examples:
328
329       Starting with the parsed URL:
330
331         use APR::URI ();
332         my $url = 'http://user:pass@example.com:80/foo?bar#item5';
333         my $parsed = APR::URI->parse($r->pool, $url);
334
335       deparse it back including and excluding parts, using different values
336       for the optional "flags" argument:
337
338       ·   Show all but the "password" fields:
339
340             print $parsed->unparse;
341
342           Prints:
343
344             http://user@example.com/foo?bar#item5
345
346           Notice that the "port" field is gone too, since it was a default
347           "port" for "scheme" "http://".
348
349       ·   Include the "password" field (by default it's not revealed)
350
351             use APR::Const -compile => qw(URI_UNP_REVEALPASSWORD);
352             print $parsed->unparse(APR::Const::URI_UNP_REVEALPASSWORD);
353
354           Prints:
355
356             http://user:pass@example.com/foo?bar#item5
357
358       ·   Show all fields but the last three, "path", "query" and "fragment":
359
360             use APR::Const -compile => qw(URI_UNP_REVEALPASSWORD
361                                           APR::Const::URI_UNP_OMITPATHINFO);
362             print $parsed->unparse(
363                 APR::Const::URI_UNP_REVEALPASSWORD⎪URI_UNP_OMITPATHINFO);
364
365           Prints:
366
367             http://user:pass@example.com
368

Copyright

373       mod_perl 2.0 and its core modules are copyrighted under The Apache
374       Software License, Version 2.0.
375

Authors

377       The mod_perl development team and numerous contributors.
378
379
380
381perl v5.8.8                       2006-11-19            docs::api::APR::URI(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors