1URI::Query(3) User Contributed Perl Documentation URI::Query(3)
2
6 URI::Query - class providing URI query string manipulation
7
9 # Constructor - using a GET query string
10 $qq = URI::Query->new($query_string);
11 # OR Constructor - using a hashref of key => value parameters
12 $qq = URI::Query->new($cgi->Vars);
13 # OR Constructor - using an array of successive keys and values
14 $qq = URI::Query->new(@params);
15 # Clone the current object
17 $qq2 = $qq->clone;
18 # Revert back to the initial constructor state (to do it all again)
20 $qq->revert;
21 # Remove all occurrences of the given parameters
23 $qq->strip('page', 'next');
24 # Remove all parameters except the given ones
26 $qq->strip_except('pagesize', 'order');
27 # Remove all empty/undefined parameters
29 $qq->strip_null;
30 # Replace all occurrences of the given parameters
32 $qq->replace(page => $page, foo => 'bar');
33 # Set the argument separator to use for output (default: unescaped '&')
35 $qq->separator(';');
36 # Output the current query string
38 print "$qq"; # OR $qq->stringify;
39 # Stringify with explicit argument separator
40 $qq->stringify(';');
41 # Output the current query string with a leading '?'
43 $qq->qstringify;
44 # Stringify with a leading '?' and an explicit argument separator
45 $qq->qstringify(';');
46 # Get a flattened hash/hashref of the current parameters
48 # (single item parameters as scalars, multiples as an arrayref)
49 my %qq = $qq->hash;
50 # Get a non-flattened hash/hashref of the current parameters
52 # (parameter => arrayref of values)
53 my %qq = $qq->hash_arrayref;
54 # Get the current query string as a set of hidden input tags
56 print $qq->hidden;
57 # Check whether the query has changed since construction
59 if ($qq->has_changed) {
60 print "changed version: $qq\n";
61 }
62
64 URI::Query provides simple URI query string manipulation, allowing you
65 to create and manipulate URI query strings from GET and POST requests
66 in web applications. This is primarily useful for creating links where
67 you wish to preserve some subset of the parameters to the current
68 request, and potentially add or replace others. Given a query string
69 this is doable with regexes, of course, but making sure you get the
70 anchoring and escaping right is tedious and error-prone - this module
71 is simpler.
72 CONSTRUCTOR
74 URI::Query objects can be constructed from scalar query strings
75 ('foo=1&bar=2&bar=3'), from a hashref which has parameters as keys, and
76 values either as scalars or arrayrefs of scalars (to handle the case of
77 parameters with multiple values e.g. { foo => '1', bar => [ '2', '3' ]
78 }), or arrays composed of successive parameters-value pairs e.g.
79 ('foo', '1', 'bar', '2', 'bar', '3'). For instance:
80 # Constructor - using a GET query string
82 $qq = URI::Query->new($query_string);
83 # Constructor - using an array of successive keys and values
85 $qq = URI::Query->new(@params);
86 # Constructor - using a hashref of key => value parameters,
88 # where values are either scalars or arrayrefs of scalars
89 $qq = URI::Query->new($cgi->Vars);
90 URI::Query also handles CGI.pm-style hashrefs, where multiple values
92 are packed into a single string, separated by the "\0" (null)
93 character.
94 All keys and values are URI unescaped at construction time, and are
96 stored and referenced unescaped. So a query string like:
97 group=prod%2Cinfra%2Ctest&op%3Aset=x%3Dy
99 is stored as:
101 'group' => 'prod,infra,test'
103 'op:set' => 'x=y'
104 You should always use the unescaped/normal variants in methods i.e.
106 $qq->replace('op:set' => 'x=z');
108 NOT:
110 $qq->replace('op%3Aset' => 'x%3Dz');
112 You can also construct a new URI::Query object by cloning an existing
114 one:
115 $qq2 = $qq->clone;
117 MODIFIER METHODS
119 All modifier methods change the state of the URI::Query object in some
120 way, and return $self, so they can be used in chained style e.g.
121 $qq->revert->strip('foo')->replace(bar => 123);
123 Note that URI::Query stashes a copy of the parameter set that existed
125 at construction time, so that any changes made by these methods can be
126 rolled back using 'revert()'. So you don't (usually) need to keep
127 multiple copies around to handle incompatible changes.
128 revert()
130 Revert the current parameter set back to that originally given at
131 construction time i.e. discard all changes made since construction.
132 strip($param1, $param2, ...)
134 Remove all occurrences of the given parameters and their values
135 from the current parameter set.
136 strip_except($param1, $param2, ...)
138 Remove all parameters EXCEPT those given from the current parameter
139 set.
140 strip_null()
142 Remove all parameters that have a value of undef from the current
143 parameter set.
144 replace($param1 => $value1, $param2, $value2, ...)
146 Replace the values of the given parameters in the current parameter
147 set with these new ones. Parameter names must be scalars, but
148 values can be either scalars or arrayrefs of scalars, when multiple
149 values are desired.
150 Note that 'replace' can also be used to add or append, since
152 there's no requirement that the parameters already exist in the
153 current parameter set.
154 strip_like($regex)
156 Remove all parameters whose names match the given (qr-quoted) regex
157 e.g.
158 $qq->strip_like(qr/^utm/)
160 Does NOT match against parameter values.
162 separator($separator)
164 Set the argument separator to use for output. Default: '&'.
165 ACCESSOR METHODS
167 has_changed()
168 If the query is actually changed by any of the modifier methods
169 (strip, strip_except, strip_null, strip_like, or replace) it sets
170 an internal changed flag which can be access by:
171 $qq->has_changed
173 revert() resets the has_changed flag to false.
175 OUTPUT METHODS
177 "$qq", stringify(), stringify($separator)
178 Return the current parameter set as a conventional param=value
179 query string, using $separator as the separator if given. e.g.
180 foo=1&bar=2&bar=3
182 Note that all parameters and values are URI escaped by stringify(),
184 so that query-string reserved characters do not occur within
185 elements. For instance, a parameter set of:
186 'group' => 'prod,infra,test'
188 'op:set' => 'x=y'
189 will be stringified as:
191 group=prod%2Cinfra%2Ctest&op%3Aset=x%3Dy
193 qstringify(), qstringify($separator)
195 Convenience method to stringify with a leading '?' e.g.
196 ?foo=1&bar=2&bar=3
198 hash()
200 Return a hash (in list context) or hashref (in scalar context) of
201 the current parameter set. Single-item parameters have scalar
202 values, while while multiple-item parameters have arrayref values
203 e.g.
204 {
206 foo => 1,
207 bar => [ 2, 3 ],
208 }
209 hash_arrayref()
211 Return a hash (in list context) or hashref (in scalar context) of
212 the current parameter set. All values are returned as arrayrefs,
213 including those with single values e.g.
214 {
216 foo => [ 1 ],
217 bar => [ 2, 3 ],
218 }
219 hidden()
221 Returns the current parameter set as a concatenated string of
222 hidden input tags, one per parameter-value e.g.
223 <input type="hidden" name="foo" value="1" />
225 <input type="hidden" name="bar" value="2" />
226 <input type="hidden" name="bar" value="3" />
227
229 Please report bugs and/or feature requests to "bug-uri-query at
230 rt.cpan.org", or through the web interface at
231 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI-Query>.
232 Should allow unescaping of input to be turned off, for situations in
234 which it's already been done. Please let me know if you find you
235 actually need this.
236 I don't think it makes sense on the output side though, since you need
238 to understand the structure of the query to escape elements correctly.
239
241 URI::Query code lives at <https://github.com/gavincarr/URI-Query>.
242 Patches / pull requests welcome!
243
245 Gavin Carr <gavin@openfusion.com.au>
246
248 Copyright 2004-2015, Gavin Carr.
249 This program is free software. You may copy or redistribute it under
251 the same terms as perl itself.
252 # vim:sw=4:et
254perl v5.36.0 2023-01-20 URI::Query(3)