Provided by: librose-uri-perl_1.02-2_all 
NAME
Rose::URI - A URI class that allows easy and efficient manipulation of URI components.
SYNOPSIS
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;
DESCRIPTION
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.
CONSTRUCTOR
new [ URI | PARAMS ]
Constructs a URI object based on URI or PARAMS, where URI is a string and PARAMS are
described below. Returns a new Rose::URI object.
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")
CLASS METHODS
default_omit_empty_query_params [BOOL]
Get or set a boolean value that determines whether or not query parameters with
"empty" (that is, undef or zero-length) values will be omitted from the query string
by default. The default value is false.
default_query_param_separator [CHARACTER]
Get or set the character used to separate query parameters in the stringified version
of Rose::URI objects. Defaults to "&".
OBJECT METHODS
abs [BASE]
This method exists solely for compatibility with URI.
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.
as_string
Returns the URI as a string. The string is "URI escaped" (reserved URI characters are
replaced with %xx sequences), but not "HTML escaped" (ampersands are not escaped, for
example).
clone
Returns a copy of the Rose::URI object.
fragment [FRAGMENT]
Get or set the fragment portion of the URI.
omit_empty_query_params [BOOL]
Get or set a boolean value that determines whether or not query parameters with
"empty" (that is, undef or zero-length) values will be omitted from the query string.
The default value is determined by the default_query_param_separator class method.
password [PASSWORD]
Get or set the password portion of the URI.
path [PATH]
Get or set the path portion of the URI.
port [PORT]
Get or set the port number portion of the URI.
query [QUERY]
Get or sets the URI's query. QUERY may be an appropriately escaped query string (e.g.
"a=1&b=2&c=a+long+string"), a reference to a hash, or a list of name/value pairs.
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.
query_form QUERY
Implementation of URI's method of the same name. This exists for backwards
compatibility purposes only and should not be used (or necessary). See the URI
documentation for more details.
query_hash
Returns the current query as a hash (in list context) or reference to a hash (in
scalar context), with multiple parameter values represented by array references (see
the query method for details).
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 }
query_param NAME [, VALUE]
Get or set a query parameter. If only NAME is passed, it returns the value of the
query parameter named NAME. Parameters with multiple values are returned as array
references. If both NAME and VALUE are passed, it sets the parameter named NAME to
VALUE, where VALUE can be a simple scalar value or a reference to an array of simple
scalar values.
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 ];
query_params NAME [, VALUE]
Same as the query_param method, except the return value is always either an array (in
list context) or reference to an array (in scalar context), even if there is only one
value.
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 )
query_param_add NAME, VALUE
Adds a new value to a query parameter. Example:
$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).
query_param_delete NAME
Deletes all instances of the parameter named NAME from the query.
query_param_exists NAME
Returns a boolean value indicating whether or not a parameter named NAME exists in the
query string.
query_param_separator [CHARACTER]
Get or set the character used to separate query parameters in the stringified version
of the URI. Defaults to the return value of the default_query_param_separator class
method ("&" by default).
rel BASE
This method exists solely for compatibility with URI.
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.
scheme [SCHEME]
Get or set the scheme portion of the URI.
userinfo
Returns the username and password attributes joined by a ":" (colon). The username and
password are not escaped in any way. If there is no password, only the username is
returned (without the colon). If neither exist, an empty string is returned.
userinfo_escaped
Returns the username and password attributes joined by a ":" (colon). The username and
password are URI-escaped, but not HTML-escaped. If there is no password, only the
username is returned (without the colon). If neither exist, an empty string is
returned.
username [USERNAME]
Get or set the username portion of the URI.
AUTHOR
John C. Siracusa (siracusa@gmail.com)
LICENSE
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.