NAME URI::Encode - Simple percent Encoding/Decoding SYNOPSIS # 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 modules provides simple URI (Percent) encoding/decoding The main purpose of this module (at least for me) was to provide an easy method to encode strings (mainly URLs) into a format which can be pasted into a plain text emails, and that those links are 'click-able' by the person reading that email. This can be accomplished by NOT encoding the reserved characters. This module can also be useful when using [HTTP::Tiny][] to ensure the URLs are properly escaped. THIS MODULE DOES NOT ENCODE RESERVED CHARACTERS BY DEFAULT. If you are looking for speed and want to encode reserved characters, use [URI::Escape::XS][] See [this script][] for a comparison on encoding results and performance. METHODS new() Creates a new object, no arguments are required 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, ["Reserved Characters"][] are also encoded. 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 again. Defaults to true. 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 provided. The $url provided is first converted into UTF-8 before percent encoding. Options set in the constructor, or defaults, can be overridden by passing them as the (optional) second argument. Options passed must be a hashref. $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 had encoded the URL using this module (or any other method), chances are that the URL was converted to UTF-8 before 'percent' encoding. Be sure to check the format and convert back if required. $uri->decode("http%3A%2F%2Fperl.com%2Ffoo%20bar"); EXPORTED FUNCTIONS The following functions are exported upon request. This provides a non-OOP interface - uri_encode($url, \%options) - uri_decode($url) CHARACTER CLASSES Reserved Characters The following characters are considered as reserved ([RFC 3986][]). They will be encoded only if requested. ! * ' ( ) ; : @ & = + $ , / ? # [ ] Unreserved Characters The following characters are considered as Unreserved. They will not be encoded a-z A-Z 0-9 - _ . ~ DEPENDENCIES [Encode][] ACKNOWLEDGEMENTS Gisle Aas for [URI::Escape][] David Nicol for [Tie::UrlEncoder][] SEE ALSO [RFC 3986][RFC 3986] [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 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][]. [HTTP::Tiny]: https://metacpan.org/pod/HTTP::Tiny [URI::Escape::XS]: https://metacpan.org/pod/URI::Escape::XS [this script]: https://github.com/mithun/perl-uri-encode/raw/master/.author/benchmark.pl ["Reserved Characters"]: #reserved-characters [RFC 3986]: http://tools.ietf.org/html/rfc3986 [Encode]: https://metacpan.org/pod/Encode [URI::Escape]: https://metacpan.org/pod/URI::Escape [Tie::UrlEncoder]: https://metacpan.org/pod/Tie::UrlEncoder [URI::Escape::JavaScript]: https://metacpan.org/pod/URI::Escape::JavaScript [perlartistic]: https://metacpan.org/pod/perlartistic