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.
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 overrided 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
URI::Escape
URI::Escape::XS
URI::Escape::JavaScript
Tie::UrlEncoder
BUGS AND LIMITATIONS
====================
Please report any bugs or feature requests to
bug-uri-encode@rt.cpan.org, or through the web interface at
http://rt.cpan.org/Public/Dist/Display.html?Name=URI-Encode
AUTHOR
======
Mithun Ayachit mithun@cpan.org
LICENSE AND COPYRIGHT
=====================
Copyright (c) 2012, 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.