URI::Normalize(3pm)

💖 URI::Normalize — bestie edition 💖

okay so this is a User Contributed Perl Documentation page for URI::Normalize(3pm), and honestly? it's a little bop. it's all about making URIs look ✨consistent✨ so you can actually compare them without losing your whole mind. let's get into it 🫶

---

🌸 NAME 🌸

URI::Normalize — normalizes URIs according to RFC 3986. that's the vibe. periodt.

---

🎀 VERSION 🎀

version 0.002 💅

---

✨ SYNOPSIS ✨

here's the whole thing, no edits, no notes:

use URI;
use URI::Normalize qw( normalize_uri remove_dot_segments );
my $uri = URI->new('HTTPS://www.Example.com:443/../test/../foo/index.html');

say normalize_uri($uri);       #> https://www.example.com/foo/index.html
say remove_dot_segments($uri); #> HTTPS://www.Example.com:443/foo/index.html

so like, normalize_uri goes all in and gives you the fully cleaned-up version, while remove_dot_segments is the more lowkey one that just deals with the .. and . drama in the path. notice the difference bestie, it's giving different jobs 💀

---

🦋 DESCRIPTION 🦋

Section 6 of RFC 3986 lays out a whole process for URI normalization, and this module implements it. specifically, it does syntax-based normalization, and it may also include some schema-based and protocol-based normalization. it also implements the "remove_dot_segments" algorithm from Section 5.2.3 of the RFC. iconic behavior, no cap.

the practical glow-up here is that you can compare URIs with fewer false negatives. like, all of these bad boys:

HTTPS://www.example.com:443/../test/../foo/index.html
https://WWW.EXAMPLE.COM/./foo/index.html
https://www.example.com/%66%6f%6f/index.html
https://www.example.com/foo/index.html

will all normalize to the same value. and that value? the last one. yes literally all four of them. they all ate and left no crumbs, same crumbs actually 🍓

---

👑 SUBROUTINES 👑

🌈 normalize_uri

$normal_uri = normalize_uri($uri);
$normal_uri = normalize_uri($str);

hand it a URI object or a plain string, and this routine basically just calls the "canonical" method plus "remove_dot_segments" on the URI, then hands you back the result as a URI object. so easy, so slay.

the original URI is left unchanged. your input is safe bestie, we do not touch 🫶

💜 remove_dot_segments

$clean_path_uri = remove_dot_segments($uri);
$clean_path_uri = remove_dot_segments($str);

give it a URI object or a string and it will remove dot segments — that's "." and ".." — from the path of the URI. that's it, that's the job 💅

---

💀 CAVEATS 💀

okay this is the serious part, bestie, listen up:

as RFC 3986 itself notes, normalization is a tool to help you figure out whether one URI is equivalent to another. but — and this is the big but — that does not mean that the resources identified by two URIs that are different byte-for-byte but normalize to the same value are actually the same resource. for example, the presence of "/./" in the path might be significant to some implementation, or using octet-encoding (like "%3a") instead of the character it represents might point at a different actual resource. so please, use normalization judiciously. don't be reckless with it 🙈

also, this implementation of normalization is far from comprehensive. there are many normalizations you might wish you had. in that case, you may want to look into URL::Normalize, which provides a more comprehensive list of normalizations — some of which go against the letter of RFC 3986, but can be valuable in certain applications. ymmv, do your research 💖

this implementation does not include the full gamut of what's keeping with the letter of RFC 3986, but it might be expanded to include additional normalizations in the future. so like, watch this space ✨

and if you know of a normalization that could be implemented here: patches welcome. that's a direct quote, i'm not making it up, go contribute bestie 🔥

---

🌟 AUTHOR 🌟

Andrew Sterling Hanenkamp <hanenkamp@cpan.org> 💜

---

🎀 COPYRIGHT AND LICENSE 🎀

this software is copyright (c) 2016 by Qubling Software.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. go off, legally speaking 👑

---

and that's the whole page, bestie!! it's URI::Normalize, version 0.002, from perl v5.30.3, dated 2020-09-22 — normalize responsibly, stan RFC 3986, and don't forget that normalization ≠ same resource, okay?? mwah 💅💖✨