URI::Query(3pm)

🦋 URI::Query — a manual page, but make it slay ✨

okay so bestie, welcome to the URI::Query man page 💖 this is a Perl module (that 3pm suffix? that's the manual section, iykyk) and honestly it's giving main character energy for anyone who has ever stared at a query string and thought "why is this my life". Let's get into it 🫶

---

💖 NAME 💖

URI::Query — class providing URI query string manipulation. that's it, that's the whole vibe 🌸

---

✨ SYNOPSIS ✨

here's the whole thing in one go, no cap:

# 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 🌈

so URI::Query gives you simple URI query string manipulation, letting you create and manipulate URI query strings from GET and POST requests in web apps. why do you care? because it's primarily useful for making links where you want to keep some subset of the parameters from the current request, and maybe add or swap out others 💅

sure, you could do this with regexes. you absolutely could. but making sure you get the anchoring and escaping right is tedious and error-prone, and honestly? not the vibe. this module is simpler. periodt.

🎀 CONSTRUCTOR 🎀

URI::Query objects can be built from a few different things, and every one of them slays:

• a scalar query string like 'foo=1&bar=2&bar=3'
• a hashref where the parameters are the keys, and the values are either scalars or arrayrefs of scalars — the arrayref thing is how you handle parameters with multiple values, like { foo => '1', bar => [ '2', '3' ] }
• arrays made of successive parameter-value pairs, like ('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 get packed into one single string, separated by the "\0" (null) character. yeah. the null character. iconic behaviour honestly 😭

all keys and values are URI unescaped at construction time, and they're stored and referenced unescaped too. so a query string like:

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

gets stored as:

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

which means you should always use the unescaped/normal variants in methods, like:

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

and NOT:

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

you can also construct a new URI::Query object by cloning an existing one, which is lowkey the easiest way to duplicate:

$qq2 = $qq->clone;

💅 MODIFIER METHODS 💅

all the modifier methods change the state of the URI::Query object somehow, and they return $self, so you can chain them like the icon you are:

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

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

• revert() — revert the current parameter set back to the one originally given at construction time, i.e. discard every change made since construction. undo button, but make it cute.
• strip($param1, $param2, ...) — remove all occurrences of the given parameters and their values from the current parameter set. gone, deleted, not invited.
• strip_except($param1, $param2, ...) — remove all parameters EXCEPT the ones given from the current parameter set. everyone else can leave.
• 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 the values can be either scalars or arrayrefs of scalars, whenever you want multiple values.

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. so it's replace and glow-up in one.

• strip_like($regex) — remove all parameters whose names match the given (qr-quoted) regex, like:

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

does NOT match against parameter values. names only, bestie.

• separator($separator) — set the argument separator to use for output. default is '&'. that & is unescaped, just so we're clear.

👑 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 you can access like:

$qq->has_changed

and revert() resets the has_changed flag to false. fresh start energy 💖

🧚 OUTPUT METHODS 🧚

• "$qq", stringify(), stringify($separator) — return the current parameter set as a conventional param=value query string, using $separator as the separator if it's 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 get scalar values, while multiple-item parameters get 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 come back as arrayrefs, including the ones 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! come through, contribute, we love to see it 🫶

---

🍓 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

---

okay bestie that's the whole page 💖 no notes, it ate, it devoured. this was perl v5.34.0, dated 2022-06-28 — and that's on URI::Query(3pm). stay escaped, stay unescaped where it counts, mwah 💅✨