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

FreeBSD Manual Pages

  
 
  

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

NAME
       URI::Query - class providing URI	query string manipulation

SYNOPSIS
	   # Constructor - using a GET query string
	   $qq = URI::Query->new($query_string);
	   # OR	Constructor - using a hashref of key =>	value parameters
	   $qq = URI::Query->new($cgi->Vars);
	   # OR	Constructor - using an array of	successive keys	and values
	   $qq = URI::Query->new(@params);

	   # Clone the current object
	   $qq2	= $qq->clone;

	   # Revert back to the	initial	constructor state (to do it all	again)
	   $qq->revert;

	   # Remove all	occurrences of the given parameters
	   $qq->strip('page', 'next');

	   # Remove all	parameters except the given ones
	   $qq->strip_except('pagesize', 'order');

	   # Remove all	empty/undefined	parameters
	   $qq->strip_null;

	   # Replace all occurrences of	the given parameters
	   $qq->replace(page =>	$page, foo => 'bar');

	   # Set the argument separator	to use for output (default: unescaped '&')
	   $qq->separator(';');

	   # Output the	current	query string
	   print "$qq";		  # OR $qq->stringify;
	   # Stringify with explicit argument separator
	   $qq->stringify(';');

	   # Output the	current	query string with a leading '?'
	   $qq->qstringify;
	   # Stringify with a leading '?' and an explicit argument separator
	   $qq->qstringify(';');

	   # Get a flattened hash/hashref of the current parameters
	   #   (single item parameters as scalars, multiples as	an arrayref)
	   my %qq = $qq->hash;

	   # Get a non-flattened hash/hashref of the current parameters
	   #   (parameter => arrayref of values)
	   my %qq = $qq->hash_arrayref;

	   # Get the current query string as a set of hidden input tags
	   print $qq->hidden;

	   # Check whether the query has changed since construction
	   if ($qq->has_changed) {
	     print "changed version: $qq\n";
	   }

DESCRIPTION
       URI::Query provides simple URI query string manipulation, allowing you
       to create and manipulate	URI query strings from GET and POST requests
       in web applications. This is primarily useful for creating links	where
       you wish	to preserve some subset	of the parameters to the current
       request,	and potentially	add or replace others. Given a query string
       this is doable with regexes, of course, but making sure you get the
       anchoring and escaping right is tedious and error-prone - this module
       is simpler.

   CONSTRUCTOR
       URI::Query objects can be constructed from scalar query strings
       ('foo=1&bar=2&bar=3'), from a hashref which has parameters as keys, and
       values either as	scalars	or arrayrefs of	scalars	(to handle the case of
       parameters with multiple	values e.g. { foo => '1', bar => [ '2',	'3' ]
       }), or arrays composed of successive parameters-value pairs e.g.
       ('foo', '1', 'bar', '2',	'bar', '3'). For instance:

	   # Constructor - using a GET query string
	   $qq = URI::Query->new($query_string);

	   # Constructor - using an array of successive	keys and values
	   $qq = URI::Query->new(@params);

	   # Constructor - using a hashref of key => value parameters,
	   # where values are either scalars or	arrayrefs of scalars
	   $qq = URI::Query->new($cgi->Vars);

       URI::Query also handles CGI.pm-style hashrefs, where multiple values
       are packed into a single	string,	separated by the "\0" (null)
       character.

       All keys	and values are URI unescaped at	construction time, and are
       stored and referenced unescaped.	So a query string like:

	   group=prod%2Cinfra%2Ctest&op%3Aset=x%3Dy

       is stored as:

	   'group'     => 'prod,infra,test'
	   'op:set'    => 'x=y'

       You should always use the unescaped/normal variants in methods i.e.

	    $qq->replace('op:set'  => 'x=z');

       NOT:

	    $qq->replace('op%3Aset'  =>	'x%3Dz');

       You can also construct a	new URI::Query object by cloning an existing
       one:

	    $qq2 = $qq->clone;

   MODIFIER METHODS
       All modifier methods change the state of	the URI::Query object in some
       way, and	return $self, so they can be used in chained style e.g.

	   $qq->revert->strip('foo')->replace(bar => 123);

       Note that URI::Query stashes a copy of the parameter set	that existed
       at construction time, so	that any changes made by these methods can be
       rolled back using 'revert()'. So	you don't (usually) need to keep
       multiple	copies around to handle	incompatible changes.

       revert()
	   Revert the current parameter	set back to that originally given at
	   construction	time i.e. discard all changes made since construction.

       strip($param1, $param2, ...)
	   Remove all occurrences of the given parameters and their values
	   from	the current parameter set.

       strip_except($param1, $param2, ...)
	   Remove all parameters EXCEPT	those given from the current parameter
	   set.

       strip_null()
	   Remove all parameters that have a value of undef from the current
	   parameter set.

       replace($param1 => $value1, $param2, $value2, ...)
	   Replace the values of the given parameters in the current parameter
	   set with these new ones. Parameter names must be scalars, but
	   values can be either	scalars	or arrayrefs of	scalars, when multiple
	   values are desired.

	   Note	that 'replace' can also	be used	to add or append, since
	   there's no requirement that the parameters already exist in the
	   current parameter set.

       strip_like($regex)
	   Remove all parameters whose names match the given (qr-quoted) regex
	   e.g.

	       $qq->strip_like(qr/^utm/)

	   Does	NOT match against parameter values.

       separator($separator)
	   Set the argument separator to use for output. Default: '&'.

   ACCESSOR METHODS
       has_changed()
	   If the query	is actually changed by any of the modifier methods
	   (strip, strip_except, strip_null, strip_like, or replace) it	sets
	   an internal changed flag which can be access	by:

	       $qq->has_changed

	   revert() resets the has_changed flag	to false.

   OUTPUT METHODS
       "$qq", stringify(), stringify($separator)
	   Return the current parameter	set as a conventional param=value
	   query string, using $separator as the separator if given. e.g.

	       foo=1&bar=2&bar=3

	   Note	that all parameters and	values are URI escaped by stringify(),
	   so that query-string	reserved characters do not occur within
	   elements. For instance, a parameter set of:

	       'group'	   => 'prod,infra,test'
	       'op:set'	   => 'x=y'

	   will	be stringified as:

	       group=prod%2Cinfra%2Ctest&op%3Aset=x%3Dy

       qstringify(), qstringify($separator)
	   Convenience method to stringify with	a leading '?' e.g.

	       ?foo=1&bar=2&bar=3

       hash()
	   Return a hash (in list context) or hashref (in scalar context) of
	   the current parameter set. Single-item parameters have scalar
	   values, while while multiple-item parameters	have arrayref values
	   e.g.

	       {
		   foo => 1,
		   bar => [ 2, 3 ],
	       }

       hash_arrayref()
	   Return a hash (in list context) or hashref (in scalar context) of
	   the current parameter set. All values are returned as arrayrefs,
	   including those with	single values e.g.

	       {
		   foo => [ 1 ],
		   bar => [ 2, 3 ],
	       }

       hidden()
	   Returns the current parameter set as	a concatenated string of
	   hidden input	tags, one per parameter-value e.g.

	       <input type="hidden" name="foo" value="1" />
	       <input type="hidden" name="bar" value="2" />
	       <input type="hidden" name="bar" value="3" />

BUGS AND CAVEATS
       Please report bugs and/or feature requests to "bug-uri-query at
       rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI-Query>.

       Should allow unescaping of input	to be turned off, for situations in
       which it's already been done. Please let	me know	if you find you
       actually	need this.

       I don't think it	makes sense on the output side though, since you need
       to understand the structure of the query	to escape elements correctly.

PATCHES
       URI::Query code lives at	<https://github.com/gavincarr/URI-Query>.
       Patches / pull requests welcome!

AUTHOR
       Gavin Carr <gavin@openfusion.com.au>

COPYRIGHT
       Copyright 2004-2015, Gavin Carr.

       This program is free software. You may copy or redistribute it under
       the same	terms as perl itself.

       # vim:sw=4:et

perl v5.32.0			  2016-08-10			 URI::Query(3)

NAME | SYNOPSIS | DESCRIPTION | BUGS AND CAVEATS | PATCHES | AUTHOR | COPYRIGHT

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

home | help