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

Copyright

360       mod_perl 2.0 and its core modules are copyrighted under The Apache
361       Software License, Version 2.0.
362

Authors

364       The mod_perl development team and numerous contributors.
365
366
367
368perl v5.32.0                      2020-07-28            docs::api::APR::URI(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors