Provided by: librose-uri-perl_1.02-2_all bug

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.

perl v5.34.0                                       2022-06-17                                     Rose::URI(3pm)