Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rose::URI(3)	      User Contributed Perl Documentation	  Rose::URI(3)

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.32.0			  2015-03-18			  Rose::URI(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | CLASS METHODS | OBJECT METHODS | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rose::URI&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help