.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Rose::URI 3pm"
.TH Rose::URI 3pm "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Rose::URI \- A URI class that allows easy and efficient manipulation of URI components.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Rose::URI;
\&
\&    $uri = Rose::URI\->new(\*(Aqhttp://un:pw@foo.com/bar/baz?a=1&b=two+3\*(Aq);
\&
\&    $scheme = $uri\->scheme;
\&    $user   = $uri\->username;
\&    $pass   = $uri\->password;
\&    $host   = $uri\->host;
\&    $path   = $uri\->path;
\&    ...
\&
\&    $b = $uri\->query_param(\*(Aqb\*(Aq);  # $b = "two 3"
\&    $a = $uri\->query_param(\*(Aqa\*(Aq);  # $a = 1
\&
\&    $uri\->query_param_delete(\*(Aqb\*(Aq);
\&    $uri\->query_param(\*(Aqc\*(Aq => \*(Aqblah blah\*(Aq);
\&    ...
\&
\&    print $uri;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Rose::URI is an alternative to \s-1URI\s0.  The important differences are as follows.
.PP
Rose::URI provides a rich set of query string manipulation methods. Query parameters can be added, removed, and checked for their existence. \s-1URI\s0 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.
.PP
Rose::URI supports query parameters with multiple values (e.g. \*(L"a=1&a=2\*(R"). \s-1URI\s0 has  limited support for this through query_form's list return value.  Better methods are available in URI::QueryParam.
.PP
Rose::URI uses Apache's C\-based \s-1URI\s0 parsing and \s-1HTML\s0 escaping functions when running in a mod_perl 1.x web server environment.
.PP
Rose::URI stores each \s-1URI\s0 \*(L"in pieces\*(R" (scheme, host, path, etc.) and then assembles those pieces when the entire \s-1URI\s0 is needed as a string. This technique is based on the assumption that the \s-1URI\s0 will be manipulated many more times than it is stringified.  If this is not the case in your usage scenario, then \s-1URI\s0 may be a better alternative.
.PP
Now some similarities: both classes use the overload module to allow \*(L"magic\*(R" stringification.  Both \s-1URI\s0 and Rose::URI objects can be printed and compared as if they were strings.
.PP
Rose::URI actually uses the \s-1URI\s0 class to do the heavy lifting of parsing URIs when not running in a mod_perl 1.x environment.
.PP
Finally, a caveat: Rose::URI  supports only \*(L"http\*(R"\-like URIs.  This includes ftp, http, https, and other similar looking URIs. \s-1URI\s0 supports many more esoteric \s-1URI\s0 types (gopher, mailto, etc.) If you need to support these formats, use \s-1URI\s0 instead.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "\fBnew [ \s-1URI\s0 | \s-1PARAMS\s0 ]\fR" 4
.IX Item "new [ URI | PARAMS ]"
Constructs a \s-1URI\s0 object based on \s-1URI\s0 or \s-1PARAMS,\s0 where \s-1URI\s0 is a string and \s-1PARAMS\s0 are described below. Returns a new Rose::URI object.
.Sp
The query string portion of the \s-1URI\s0 argument may use either \*(L"&\*(R" or \*(L";\*(R" as the parameter separator. Examples:
.Sp
.Vb 2
\&    $uri = Rose::URI\->new(\*(Aq/foo?a=1&b=2\*(Aq);
\&    $uri = Rose::URI\->new(\*(Aq/foo?a=1;b=2\*(Aq); # same thing
.Ve
.Sp
The query_param_separator parameter determines what is used when the query string (or the whole \s-1URI\s0) is output as a string later.
.Sp
Rose::URI uses \s-1URI\s0 or Apache::URI (when running under mod_perl 1.x) to do its \s-1URI\s0 string parsing.
.Sp
Valid \s-1PARAMS\s0 are:
.Sp
.Vb 8
\&    fragment
\&    host
\&    password
\&    path
\&    port
\&    query
\&    scheme
\&    username
\&
\&    query_param_separator
.Ve
.Sp
Which correspond to the following \s-1URI\s0 pieces:
.Sp
.Vb 1
\&    <scheme>://<username:password>@<path>?<query>#<fragment>
.Ve
.Sp
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 \*(L"&\*(R" by default (e.g. \*(L"a=1&b=2\*(R")
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "\fBdefault_omit_empty_query_params [\s-1BOOL\s0]\fR" 4
.IX Item "default_omit_empty_query_params [BOOL]"
Get or set a boolean value that determines whether or not query parameters with \*(L"empty\*(R" (that is, undef or zero-length) values will be omitted from the query string by default.  The default value is false.
.IP "\fBdefault_query_param_separator [\s-1CHARACTER\s0]\fR" 4
.IX Item "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 \*(L"&\*(R".
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.IP "\fBabs [\s-1BASE\s0]\fR" 4
.IX Item "abs [BASE]"
This method exists solely for compatibility with \s-1URI\s0.
.Sp
Returns an absolute Rose::URI object.  If the current \s-1URI\s0 is already absolute, then a reference to it is simply returned.  If the current \s-1URI\s0 is relative, then a new absolute \s-1URI\s0 is constructed by combining the \s-1URI\s0 and the \s-1BASE,\s0 and returned.
.IP "\fBas_string\fR" 4
.IX Item "as_string"
Returns the \s-1URI\s0 as a string.  The string is \*(L"\s-1URI\s0 escaped\*(R" (reserved \s-1URI\s0 characters are replaced with \f(CW%xx\fR sequences), but not \*(L"\s-1HTML\s0 escaped\*(R" (ampersands are not escaped, for example).
.IP "\fBclone\fR" 4
.IX Item "clone"
Returns a copy of the Rose::URI object.
.IP "\fBfragment [\s-1FRAGMENT\s0]\fR" 4
.IX Item "fragment [FRAGMENT]"
Get or set the fragment portion of the \s-1URI.\s0
.IP "\fBomit_empty_query_params [\s-1BOOL\s0]\fR" 4
.IX Item "omit_empty_query_params [BOOL]"
Get or set a boolean value that determines whether or not query parameters with \*(L"empty\*(R" (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.
.IP "\fBpassword [\s-1PASSWORD\s0]\fR" 4
.IX Item "password [PASSWORD]"
Get or set the password portion of the \s-1URI.\s0
.IP "\fBpath [\s-1PATH\s0]\fR" 4
.IX Item "path [PATH]"
Get or set the path portion of the \s-1URI.\s0
.IP "\fBport [\s-1PORT\s0]\fR" 4
.IX Item "port [PORT]"
Get or set the port number portion of the \s-1URI.\s0
.IP "\fBquery [\s-1QUERY\s0]\fR" 4
.IX Item "query [QUERY]"
Get or sets the \s-1URI\s0's query.  \s-1QUERY\s0 may be an appropriately escaped query string (e.g. \*(L"a=1&b=2&c=a+long+string\*(R"), a reference to a hash, or a list of name/value pairs.
.Sp
Query strings may use either \*(L"&\*(R" or \*(L";\*(R" as their query separator. If a \*(L"&\*(R" character exists anywhere in the query string, it is assumed to be the separator.
.Sp
If none of the characters \*(L"&\*(R", \*(L";\*(R", or \*(L"=\*(R" appears in the query string, then the entire query string is taken as a single parameter name with an undefined value.
.Sp
Hashes and lists should specify multiple parameter values using array references.
.Sp
Here are some examples representing the query string \*(L"a=1&a=2&b=3\*(R"
.Sp
.Vb 4
\&    $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
.Ve
.Sp
Returns the current (or new) query as a URI-escaped (but not HTML-escaped) query string.
.IP "\fBquery_form \s-1QUERY\s0\fR" 4
.IX Item "query_form QUERY"
Implementation of \s-1URI\s0's method of the same name.  This exists for backwards compatibility purposes only and should not be used (or necessary).  See the \s-1URI\s0 documentation for more details.
.IP "\fBquery_hash\fR" 4
.IX Item "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).
.Sp
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.
.Sp
Example:
.Sp
.Vb 1
\&    $uri = Rose::URI\->new(\*(Aq/foo?a=1&b=2&a=2\*(Aq);
\&
\&    $h = $uri\->query_hash; # $h = { a => [ 1, 2 ], b => 2 }
.Ve
.IP "\fBquery_param \s-1NAME\s0 [, \s-1VALUE\s0]\fR" 4
.IX Item "query_param NAME [, VALUE]"
Get or set a query parameter.  If only \s-1NAME\s0 is passed, it returns the value of the query parameter named \s-1NAME.\s0  Parameters with multiple values are returned as array references.  If both \s-1NAME\s0 and \s-1VALUE\s0 are passed, it sets the parameter named \s-1NAME\s0 to \s-1VALUE,\s0 where \s-1VALUE\s0 can be a simple scalar value or a reference to an array of simple scalar values.
.Sp
Examples:
.Sp
.Vb 1
\&    $uri = Rose::URI\->new(\*(Aq/foo?a=1\*(Aq);
\&
\&    $a = $uri\->query_param(\*(Aqa\*(Aq); # $a = 1
\&
\&    $uri\->query_param(\*(Aqa\*(Aq => 3); # query string is now "a=3"
\&
\&    $uri\->query_param(\*(Aqb\*(Aq => [ 4, 5 ]); # now "a=3&b=4&b=5"
\&
\&    $b = $uri\->query_param(\*(Aqb\*(Aq); # $b = [ 4, 5 ];
.Ve
.IP "\fBquery_params \s-1NAME\s0 [, \s-1VALUE\s0]\fR" 4
.IX Item "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.
.Sp
Examples:
.Sp
.Vb 1
\&    $uri = Rose::URI\->new(\*(Aq/foo?a=1&b=1&b=2\*(Aq);
\&
\&    $a = $uri\->query_params(\*(Aqa\*(Aq); # $a = [ 1 ]
\&    @a = $uri\->query_params(\*(Aqa\*(Aq); # @a = ( 1 )
\&
\&    $b = $uri\->query_params(\*(Aqa\*(Aq); # $b = [ 1, 2 ]
\&    @b = $uri\->query_params(\*(Aqa\*(Aq); # @b = ( 1, 2 )
.Ve
.IP "\fBquery_param_add \s-1NAME, VALUE\s0\fR" 4
.IX Item "query_param_add NAME, VALUE"
Adds a new value to a query parameter.   Example:
.Sp
.Vb 1
\&    $uri = Rose::URI\->new(\*(Aq/foo?a=1&b=1\*(Aq);
\&
\&    $a = $uri\->query_param_add(\*(Aqb\*(Aq => 2); # now "a=2&b=1&b=2"
.Ve
.Sp
Returns an array (in list context) or reference to an array (in scalar context) of the new parameter value(s).
.IP "\fBquery_param_delete \s-1NAME\s0\fR" 4
.IX Item "query_param_delete NAME"
Deletes all instances of the parameter named \s-1NAME\s0 from the query.
.IP "\fBquery_param_exists \s-1NAME\s0\fR" 4
.IX Item "query_param_exists NAME"
Returns a boolean value indicating whether or not a parameter named \s-1NAME\s0 exists in the query string.
.IP "\fBquery_param_separator [\s-1CHARACTER\s0]\fR" 4
.IX Item "query_param_separator [CHARACTER]"
Get or set the character used to separate query parameters in the stringified version of the \s-1URI.\s0  Defaults to the return value of the default_query_param_separator class method (\*(L"&\*(R" by default).
.IP "\fBrel \s-1BASE\s0\fR" 4
.IX Item "rel BASE"
This method exists solely for compatibility with \s-1URI\s0.
.Sp
Returns a relative \s-1URI\s0 reference if it is possible to make one that denotes the same resource relative to \s-1BASE.\s0  If not, then the current \s-1URI\s0 is simply returned.
.IP "\fBscheme [\s-1SCHEME\s0]\fR" 4
.IX Item "scheme [SCHEME]"
Get or set the scheme portion of the \s-1URI.\s0
.IP "\fBuserinfo\fR" 4
.IX Item "userinfo"
Returns the username and password attributes joined by a \*(L":\*(R" (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.
.IP "\fBuserinfo_escaped\fR" 4
.IX Item "userinfo_escaped"
Returns the username and password attributes joined by a \*(L":\*(R" (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.
.IP "\fBusername [\s-1USERNAME\s0]\fR" 4
.IX Item "username [USERNAME]"
Get or set the username portion of the \s-1URI.\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
John C. Siracusa (siracusa@gmail.com)
.SH "LICENSE"
.IX Header "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.