1URI::Query(3)         User Contributed Perl Documentation        URI::Query(3)
2
3
4

NAME

6       URI::Query - class providing URI query string manipulation
7

SYNOPSIS

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
16           # Clone the current object
17           $qq2 = $qq->clone;
18
19           # Revert back to the initial constructor state (to do it all again)
20           $qq->revert;
21
22           # Remove all occurrences of the given parameters
23           $qq->strip('page', 'next');
24
25           # Remove all parameters except the given ones
26           $qq->strip_except('pagesize', 'order');
27
28           # Remove all empty/undefined parameters
29           $qq->strip_null;
30
31           # Replace all occurrences of the given parameters
32           $qq->replace(page => $page, foo => 'bar');
33
34           # Set the argument separator to use for output (default: unescaped '&')
35           $qq->separator(';');
36
37           # Output the current query string
38           print "$qq";           # OR $qq->stringify;
39           # Stringify with explicit argument separator
40           $qq->stringify(';');
41
42           # 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
47           # 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
51           # Get a non-flattened hash/hashref of the current parameters
52           #   (parameter => arrayref of values)
53           my %qq = $qq->hash_arrayref;
54
55           # Get the current query string as a set of hidden input tags
56           print $qq->hidden;
57
58           # Check whether the query has changed since construction
59           if ($qq->has_changed) {
60             print "changed version: $qq\n";
61           }
62

DESCRIPTION

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
73   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
81           # Constructor - using a GET query string
82           $qq = URI::Query->new($query_string);
83
84           # Constructor - using an array of successive keys and values
85           $qq = URI::Query->new(@params);
86
87           # 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
91       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
95       All keys and values are URI unescaped at construction time, and are
96       stored and referenced unescaped. So a query string like:
97
98           group=prod%2Cinfra%2Ctest&op%3Aset=x%3Dy
99
100       is stored as:
101
102           'group'     => 'prod,infra,test'
103           'op:set'    => 'x=y'
104
105       You should always use the unescaped/normal variants in methods i.e.
106
107            $qq->replace('op:set'  => 'x=z');
108
109       NOT:
110
111            $qq->replace('op%3Aset'  => 'x%3Dz');
112
113       You can also construct a new URI::Query object by cloning an existing
114       one:
115
116            $qq2 = $qq->clone;
117
118   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
122           $qq->revert->strip('foo')->replace(bar => 123);
123
124       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
129       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
133       strip($param1, $param2, ...)
134           Remove all occurrences of the given parameters and their values
135           from the current parameter set.
136
137       strip_except($param1, $param2, ...)
138           Remove all parameters EXCEPT those given from the current parameter
139           set.
140
141       strip_null()
142           Remove all parameters that have a value of undef from the current
143           parameter set.
144
145       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
151           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
155       strip_like($regex)
156           Remove all parameters whose names match the given (qr-quoted) regex
157           e.g.
158
159               $qq->strip_like(qr/^utm/)
160
161           Does NOT match against parameter values.
162
163       separator($separator)
164           Set the argument separator to use for output. Default: '&'.
165
166   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
172               $qq->has_changed
173
174           revert() resets the has_changed flag to false.
175
176   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
181               foo=1&bar=2&bar=3
182
183           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
187               'group'     => 'prod,infra,test'
188               'op:set'    => 'x=y'
189
190           will be stringified as:
191
192               group=prod%2Cinfra%2Ctest&op%3Aset=x%3Dy
193
194       qstringify(), qstringify($separator)
195           Convenience method to stringify with a leading '?' e.g.
196
197               ?foo=1&bar=2&bar=3
198
199       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
205               {
206                   foo => 1,
207                   bar => [ 2, 3 ],
208               }
209
210       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
215               {
216                   foo => [ 1 ],
217                   bar => [ 2, 3 ],
218               }
219
220       hidden()
221           Returns the current parameter set as a concatenated string of
222           hidden input tags, one per parameter-value e.g.
223
224               <input type="hidden" name="foo" value="1" />
225               <input type="hidden" name="bar" value="2" />
226               <input type="hidden" name="bar" value="3" />
227

BUGS AND CAVEATS

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
233       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
237       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

PATCHES

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

AUTHOR

245       Gavin Carr <gavin@openfusion.com.au>
246
248       Copyright 2004-2015, Gavin Carr.
249
250       This program is free software. You may copy or redistribute it under
251       the same terms as perl itself.
252
253       # vim:sw=4:et
254
255
256
257perl v5.38.0                      2023-07-21                     URI::Query(3)
Impressum