URI::Encode(3pm)

👑 URI::Encode — bestie, let's talk percent-encoding ✨

okay so this is the manual page for URI::Encode (that's the Perl module, URI::Encode(3pm), from the User Contributed Perl Documentation crew 💅). It's a cute little module that does simple URI (percent) encoding and decoding, and honestly? It ate. Let's get into it 🫶

---

🌸 NAME 🌸

URI::Encode — Simple percent Encoding/Decoding. That's the whole name, no notes, periodt ✨

---

🦋 SYNOPSIS 🦋

Two ways to use it: the OOP girlie route, and the functional route. Both iconic, pick your fighter 💖

# OOP Interface
use URI::Encode;
my $uri     = URI::Encode->new( { encode_reserved => 0 } );
my $encoded = $uri->encode($data);
my $decoded = $uri->decode($encoded);

# Functional
use URI::Encode qw(uri_encode uri_decode);
my $encoded = uri_encode($data);
my $decoded = uri_decode($encoded);

---

🌈 DESCRIPTION 🌈

This module provides simple URI (Percent) encoding/decoding. Lowkey exactly what it says on the tin 💅

The main purpose of this module (at least for the author, and honestly same energy) was to give you an easy method to encode strings — mainly URLs — into a format that can be pasted into plain text emails, where those links stay 'click-able' for whoever's reading that email 👑. You pull this off by NOT encoding the reserved characters. No cap, that's the trick.

It's also useful when you're working with HTTP::Tiny and you want to make sure your URLs are properly escaped 🧚

Heads up bestie: this module does not encode reserved characters by default. If you're chasing speed and you do want reserved characters encoded, go use URI::Escape::XS instead 💀

There's a script at https://github.com/mithun/perl-uri-encode/raw/master/.author/benchmark.pl that compares encoding results and performance, if you're nosy like me 🙈

---

💅 METHODS 💅

✨ new() ✨

Creates a new object — no arguments required, she's low-maintenance 🌸

my $encoder = URI::Encode->new(\%options);

The following options can be passed to the constructor:

• encode_reserved — my $encoder = URI::Encode->new({encode_reserved => 0});

If true, the "Reserved Characters" get encoded too. Defaults to false. 💜

• double_encode — my $encoder = URI::Encode->new({double_encode => 1});

If false, characters that are already percent-encoded will not be encoded a second time. Defaults to true. So check it:

my $encoder = URI::Encode->new({double_encode => 0});
print $encoder->encode('http://perl.com/foo%20bar'); # prints http://perl.com/foo%20bar

✨ encode($url, \%options) ✨

This method encodes the URL you hand it. The $url you provide gets converted into UTF-8 first, and then percent encoded 🎀 Options set in the constructor — or the defaults — can be overridden by passing them as the (optional) second argument. Those options must be a hashref, no substitutes 💅

$uri->encode("http://perl.com/foo bar");
$uri->encode( "http://perl.com/foo bar", { encode_reserved => 1 } );

✨ decode($url) ✨

This method decodes a 'percent' encoded URL 🦋 If you encoded the URL using this module (or literally any other method), chances are the URL was converted to UTF-8 before the 'percent' encoding happened. So be sure to check the format and convert back if you need to — fr fr, don't skip that step 😭

$uri->decode("http%3A%2F%2Fperl.com%2Ffoo%20bar");

---

🎀 EXPORTED FUNCTIONS 🎀

The following functions are exported upon request. This is the non-OOP interface, for when you just want the functions and none of the object drama 💖

• uri_encode($url, \%options)
• uri_decode($url)

---

⭐ CHARACTER CLASSES ⭐

🌸 Reserved Characters 🌸

These characters are considered reserved, per RFC 3986 (http://tools.ietf.org/html/rfc3986). They only get encoded if you request it — otherwise they stay unbothered and thriving 👑

 ! * ' ( ) ; : @ & = + $ , / ? # [ ]

🦋 Unreserved Characters 🦋

These ones are considered Unreserved. They will not be encoded, periodt:

a-z
A-Z
0-9
- _ . ~

---

💜 DEPENDENCIES 💜

• Encode

---

🫶 ACKNOWLEDGEMENTS 🫶

• Gisle Aas for URI::Escape
• David Nicol for Tie::UrlEncoder

shoutout to the legends, we love to see it 💖

---

🔥 SEE ALSO 🔥

• RFC 3986 — http://tools.ietf.org/html/rfc3986
• URI::Escape
• URI::Escape::XS
• URI::Escape::JavaScript
• Tie::UrlEncoder

---

💀 BUGS AND LIMITATIONS 💀

Please report any bugs or feature requests at https://github.com/mithun/perl-uri-encode/issues 🙈 Don't suffer in silence bestie, tell the maintainer.

---

👑 AUTHOR 👑

Mithun Ayachit mithun@cpan.org ✨

---

🌈 LICENSE AND COPYRIGHT 🌈

Copyright (c) 2014, Mithun Ayachit. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. 💅

---

and that's the whole page, bestie!! this one comes to you from the User Contributed Perl Documentation corner of the world, perl v5.36.0, dated 2022-10-13 — so yes, it's giving slightly vintage but she still serves 🎀 go forth and percent-encode responsibly, mwah 💖✨🦋