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);
# 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(';');
# 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;
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');
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.
- separator($separator)
- Set the argument separator to use for output. Default: '&'.
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
- 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
<
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
<
https://github.com/gavincarr/URI-Query>. Patches / pull requests
welcome!
AUTHOR¶
Gavin Carr <gavin@openfusion.com.au>
COPYRIGHT¶
Copyright 2004-2011, Gavin Carr. All Rights Reserved.
This program is free software. You may copy or redistribute it under the same
terms as perl itself.