| 1 |
|
| 2 |
|
| 3 |
NAME |
| 4 |
|
| 5 |
|
| 6 |
URI::Encode - Simple percent Encoding/Decoding |
| 7 |
|
| 8 |
<a href="https://travis-ci.org/mithun/perl-uri-encode"><img src="https://travis-ci.org/mithun/perl-uri-encode.svg?branch=master"></a> |
| 9 |
|
| 10 |
|
| 11 |
|
| 12 |
SYNOPSIS |
| 13 |
|
| 14 |
|
| 15 |
# OOP Interface |
| 16 |
use URI::Encode; |
| 17 |
my $uri = URI::Encode->new( { encode_reserved => 0 } ); |
| 18 |
my $encoded = $uri->encode($data); |
| 19 |
my $decoded = $uri->decode($encoded); |
| 20 |
|
| 21 |
# Functional |
| 22 |
use URI::Encode qw(uri_encode uri_decode); |
| 23 |
my $encoded = uri_encode($data); |
| 24 |
my $decoded = uri_decode($encoded); |
| 25 |
|
| 26 |
|
| 27 |
|
| 28 |
DESCRIPTION |
| 29 |
|
| 30 |
|
| 31 |
This modules provides simple URI (Percent) encoding/decoding |
| 32 |
|
| 33 |
The main purpose of this module (at least for me) was to provide an easy |
| 34 |
method to encode strings (mainly URLs) into a format which can be pasted |
| 35 |
into a plain text emails, and that those links are 'click-able' by the |
| 36 |
person reading that email. This can be accomplished by NOT encoding the |
| 37 |
reserved characters. |
| 38 |
|
| 39 |
This module can also be useful when using [HTTP::Tiny][] to ensure the |
| 40 |
URLs are properly escaped. |
| 41 |
|
| 42 |
THIS MODULE DOES NOT ENCODE RESERVED CHARACTERS BY DEFAULT. If you are |
| 43 |
looking for speed and want to encode reserved characters, use |
| 44 |
[URI::Escape::XS][] |
| 45 |
|
| 46 |
See [this script][] for a comparison on encoding results and |
| 47 |
performance. |
| 48 |
|
| 49 |
|
| 50 |
|
| 51 |
METHODS |
| 52 |
|
| 53 |
|
| 54 |
new() |
| 55 |
|
| 56 |
Creates a new object, no arguments are required |
| 57 |
|
| 58 |
my $encoder = URI::Encode->new(\%options); |
| 59 |
|
| 60 |
The following options can be passed to the constructor |
| 61 |
|
| 62 |
- encode_reserved |
| 63 |
|
| 64 |
my $encoder = URI::Encode->new({encode_reserved => 0}); |
| 65 |
|
| 66 |
If true, ["Reserved Characters"][] are also encoded. Defaults |
| 67 |
to false. |
| 68 |
|
| 69 |
- double_encode |
| 70 |
|
| 71 |
my $encoder = URI::Encode->new({double_encode => 1}); |
| 72 |
|
| 73 |
If false, characters that are already percent-encoded will not be |
| 74 |
encoded again. Defaults to true. |
| 75 |
|
| 76 |
my $encoder = URI::Encode->new({double_encode => 0}); |
| 77 |
print $encoder->encode('http://perl.com/foo%20bar'); # prints http://perl.com/foo%20bar |
| 78 |
|
| 79 |
|
| 80 |
encode($url, \%options) |
| 81 |
|
| 82 |
This method encodes the URL provided. The $url provided is first |
| 83 |
converted into UTF-8 before percent encoding. Options set in the |
| 84 |
constructor, or defaults, can be overridden by passing them as the |
| 85 |
(optional) second argument. Options passed must be a hashref. |
| 86 |
|
| 87 |
$uri->encode("http://perl.com/foo bar"); |
| 88 |
$uri->encode( "http://perl.com/foo bar", { encode_reserved => 1 } ); |
| 89 |
|
| 90 |
|
| 91 |
decode($url) |
| 92 |
|
| 93 |
This method decodes a 'percent' encoded URL. If you had encoded the URL |
| 94 |
using this module (or any other method), chances are that the URL was |
| 95 |
converted to UTF-8 before 'percent' encoding. Be sure to check the |
| 96 |
format and convert back if required. |
| 97 |
|
| 98 |
$uri->decode("http%3A%2F%2Fperl.com%2Ffoo%20bar"); |
| 99 |
|
| 100 |
|
| 101 |
|
| 102 |
EXPORTED FUNCTIONS |
| 103 |
|
| 104 |
|
| 105 |
The following functions are exported upon request. This provides a |
| 106 |
non-OOP interface |
| 107 |
|
| 108 |
- uri_encode($url, \%options) |
| 109 |
- uri_decode($url) |
| 110 |
|
| 111 |
|
| 112 |
|
| 113 |
CHARACTER CLASSES |
| 114 |
|
| 115 |
|
| 116 |
Reserved Characters |
| 117 |
|
| 118 |
The following characters are considered as reserved ([RFC 3986][]). They |
| 119 |
will be encoded only if requested. |
| 120 |
|
| 121 |
! * ' ( ) ; : @ & = + $ , / ? # [ ] |
| 122 |
|
| 123 |
|
| 124 |
Unreserved Characters |
| 125 |
|
| 126 |
The following characters are considered as Unreserved. They will not be |
| 127 |
encoded |
| 128 |
|
| 129 |
a-z |
| 130 |
A-Z |
| 131 |
0-9 |
| 132 |
- _ . ~ |
| 133 |
|
| 134 |
|
| 135 |
|
| 136 |
DEPENDENCIES |
| 137 |
|
| 138 |
|
| 139 |
[Encode][] |
| 140 |
|
| 141 |
|
| 142 |
|
| 143 |
ACKNOWLEDGEMENTS |
| 144 |
|
| 145 |
|
| 146 |
Gisle Aas for [URI::Escape][] |
| 147 |
|
| 148 |
David Nicol for [Tie::UrlEncoder][] |
| 149 |
|
| 150 |
|
| 151 |
|
| 152 |
SEE ALSO |
| 153 |
|
| 154 |
|
| 155 |
[RFC 3986][RFC 3986] |
| 156 |
|
| 157 |
[URI::Escape][] |
| 158 |
|
| 159 |
[URI::Escape::XS][] |
| 160 |
|
| 161 |
[URI::Escape::JavaScript][] |
| 162 |
|
| 163 |
[Tie::UrlEncoder][] |
| 164 |
|
| 165 |
|
| 166 |
|
| 167 |
BUGS AND LIMITATIONS |
| 168 |
|
| 169 |
|
| 170 |
Please report any bugs or feature requests at |
| 171 |
https://github.com/mithun/perl-uri-encode/issues |
| 172 |
|
| 173 |
|
| 174 |
|
| 175 |
AUTHOR |
| 176 |
|
| 177 |
|
| 178 |
Mithun Ayachit [email protected] |
| 179 |
|
| 180 |
|
| 181 |
|
| 182 |
LICENSE AND COPYRIGHT |
| 183 |
|
| 184 |
|
| 185 |
Copyright (c) 2014, Mithun Ayachit. All rights reserved. |
| 186 |
|
| 187 |
This module is free software; you can redistribute it and/or modify it |
| 188 |
under the same terms as Perl itself. See [perlartistic][]. |
| 189 |
|
| 190 |
[HTTP::Tiny]: https://metacpan.org/pod/HTTP::Tiny |
| 191 |
[URI::Escape::XS]: https://metacpan.org/pod/URI::Escape::XS |
| 192 |
[this script]: https://github.com/mithun/perl-uri-encode/raw/master/.author/benchmark.pl |
| 193 |
["Reserved Characters"]: #reserved-characters |
| 194 |
[RFC 3986]: http://tools.ietf.org/html/rfc3986 |
| 195 |
[Encode]: https://metacpan.org/pod/Encode |
| 196 |
[URI::Escape]: https://metacpan.org/pod/URI::Escape |
| 197 |
[Tie::UrlEncoder]: https://metacpan.org/pod/Tie::UrlEncoder |
| 198 |
[URI::Escape::JavaScript]: https://metacpan.org/pod/URI::Escape::JavaScript |
| 199 |
[perlartistic]: https://metacpan.org/pod/perlartistic |