| Rose::URI(3pm) | User Contributed Perl Documentation | Rose::URI(3pm) |
Rose::URI - A URI class that allows easy and efficient manipulation of URI components.
use Rose::URI;
$uri = Rose::URI->new('http://un:pw@foo.com/bar/baz?a=1&b=two+3');
$scheme = $uri->scheme;
$user = $uri->username;
$pass = $uri->password;
$host = $uri->host;
$path = $uri->path;
...
$b = $uri->query_param('b'); # $b = "two 3"
$a = $uri->query_param('a'); # $a = 1
$uri->query_param_delete('b');
$uri->query_param('c' => 'blah blah');
...
print $uri;
Rose::URI is an alternative to URI. The important differences are as follows.
Rose::URI provides a rich set of query string manipulation methods. Query parameters can be added, removed, and checked for their existence. URI allows the entire query to be set or returned as a whole via the query_form or query methods, and the URI::QueryParam module provides a few more methods for query string manipulation.
Rose::URI supports query parameters with multiple values (e.g. "a=1&a=2"). URI has limited support for this through query_form's list return value. Better methods are available in URI::QueryParam.
Rose::URI uses Apache's C-based URI parsing and HTML escaping functions when running in a mod_perl 1.x web server environment.
Rose::URI stores each URI "in pieces" (scheme, host, path, etc.) and then assembles those pieces when the entire URI is needed as a string. This technique is based on the assumption that the URI will be manipulated many more times than it is stringified. If this is not the case in your usage scenario, then URI may be a better alternative.
Now some similarities: both classes use the overload module to allow "magic" stringification. Both URI and Rose::URI objects can be printed and compared as if they were strings.
Rose::URI actually uses the URI class to do the heavy lifting of parsing URIs when not running in a mod_perl 1.x environment.
Finally, a caveat: Rose::URI supports only "http"-like URIs. This includes ftp, http, https, and other similar looking URIs. URI supports many more esoteric URI types (gopher, mailto, etc.) If you need to support these formats, use URI instead.
The query string portion of the URI argument may use either "&" or ";" as the parameter separator. Examples:
$uri = Rose::URI->new('/foo?a=1&b=2');
$uri = Rose::URI->new('/foo?a=1;b=2'); # same thing
The query_param_separator parameter determines what is used when the query string (or the whole URI) is output as a string later.
Rose::URI uses URI or Apache::URI (when running under mod_perl 1.x) to do its URI string parsing.
Valid PARAMS are:
fragment
host
password
path
port
query
scheme
username
query_param_separator
Which correspond to the following URI pieces:
<scheme>://<username:password>@<path>?<query>#<fragment>
All the above parameters accept strings. See below for more information about the query parameter. The query_param_separator parameter determines the separator used when constructing the query string. It is "&" by default (e.g. "a=1&b=2")
Returns an absolute Rose::URI object. If the current URI is already absolute, then a reference to it is simply returned. If the current URI is relative, then a new absolute URI is constructed by combining the URI and the BASE, and returned.
Query strings may use either "&" or ";" as their query separator. If a "&" character exists anywhere in the query string, it is assumed to be the separator.
If none of the characters "&", ";", or "=" appears in the query string, then the entire query string is taken as a single parameter name with an undefined value.
Hashes and lists should specify multiple parameter values using array references.
Here are some examples representing the query string "a=1&a=2&b=3"
$uri->query("a=1&a=2&b=3"); # string
$uri->query("a=1;a=2;b=3"); # same thing
$uri->query({ a => [ 1, 2 ], b => 3 }); # hash ref
$uri->query(a => [ 1, 2 ], b => 3); # list
Returns the current (or new) query as a URI-escaped (but not HTML-escaped) query string.
The return value is a shallow copy of the actual query hash. It should be treated as read-only unless you really know what you are doing.
Example:
$uri = Rose::URI->new('/foo?a=1&b=2&a=2');
$h = $uri->query_hash; # $h = { a => [ 1, 2 ], b => 2 }
Examples:
$uri = Rose::URI->new('/foo?a=1');
$a = $uri->query_param('a'); # $a = 1
$uri->query_param('a' => 3); # query string is now "a=3"
$uri->query_param('b' => [ 4, 5 ]); # now "a=3&b=4&b=5"
$b = $uri->query_param('b'); # $b = [ 4, 5 ];
Examples:
$uri = Rose::URI->new('/foo?a=1&b=1&b=2');
$a = $uri->query_params('a'); # $a = [ 1 ]
@a = $uri->query_params('a'); # @a = ( 1 )
$b = $uri->query_params('a'); # $b = [ 1, 2 ]
@b = $uri->query_params('a'); # @b = ( 1, 2 )
$uri = Rose::URI->new('/foo?a=1&b=1');
$a = $uri->query_param_add('b' => 2); # now "a=2&b=1&b=2"
Returns an array (in list context) or reference to an array (in scalar context) of the new parameter value(s).
Returns a relative URI reference if it is possible to make one that denotes the same resource relative to BASE. If not, then the current URI is simply returned.
John C. Siracusa (siracusa@gmail.com)
Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
| 2022-06-17 | perl v5.34.0 |