1URI::Encode(3)        User Contributed Perl Documentation       URI::Encode(3)
2
3
4

NAME

6       URI::Encode - Simple percent Encoding/Decoding
7

SYNOPSIS

9           # OOP Interface
10           use URI::Encode;
11           my $uri     = URI::Encode->new( { encode_reserved => 0 } );
12           my $encoded = $uri->encode($data);
13           my $decoded = $uri->decode($encoded);
14
15           # Functional
16           use URI::Encode qw(uri_encode uri_decode);
17           my $encoded = uri_encode($data);
18           my $decoded = uri_decode($encoded);
19

DESCRIPTION

21       This modules provides simple URI (Percent) encoding/decoding
22
23       The main purpose of this module (at least for me) was to provide an
24       easy method to encode strings (mainly URLs) into a format which can be
25       pasted into a plain text emails, and that those links are 'click-able'
26       by the person reading that email. This can be accomplished by NOT
27       encoding the reserved characters.
28
29       This module can also be useful when using HTTP::Tiny to ensure the URLs
30       are properly escaped.
31
32       This module does not encode reserved characters by default. If you are
33       looking for speed and want to encode reserved characters, use
34       URI::Escape::XS
35
36       See this script <https://github.com/mithun/perl-uri-
37       encode/raw/master/.author/benchmark.pl> for a comparison on encoding
38       results and performance.
39

METHODS

41   new()
42       Creates a new object, no arguments are required
43
44           my $encoder = URI::Encode->new(\%options);
45
46       The following options can be passed to the constructor
47
48       encode_reserved
49               my $encoder = URI::Encode->new({encode_reserved => 0});
50
51           If true, "Reserved Characters" are also encoded. Defaults to false.
52
53       double_encode
54               my $encoder = URI::Encode->new({double_encode => 1});
55
56           If false, characters that are already percent-encoded will not be
57           encoded again. Defaults to true.
58
59               my $encoder = URI::Encode->new({double_encode => 0});
60               print $encoder->encode('http://perl.com/foo%20bar'); # prints http://perl.com/foo%20bar
61
62   "encode($url, \%options)"
63       This method encodes the URL provided. The $url provided is first
64       converted into UTF-8 before percent encoding. Options set in the
65       constructor, or defaults, can be overridden by passing them as the
66       (optional) second argument. Options passed must be a hashref.
67
68           $uri->encode("http://perl.com/foo bar");
69           $uri->encode( "http://perl.com/foo bar", { encode_reserved => 1 } );
70
71   decode($url)
72       This method decodes a 'percent' encoded URL. If you had encoded the URL
73       using this module (or any other method), chances are that the URL was
74       converted to UTF-8 before 'percent' encoding. Be sure to check the
75       format and convert back if required.
76
77           $uri->decode("http%3A%2F%2Fperl.com%2Ffoo%20bar");
78

EXPORTED FUNCTIONS

80       The following functions are exported upon request. This provides a non-
81       OOP interface
82
83       "uri_encode($url, \%options)"
84       uri_decode($url)
85

CHARACTER CLASSES

87   Reserved Characters
88       The following characters are considered as reserved (RFC 3986
89       <http://tools.ietf.org/html/rfc3986>). They will be encoded only if
90       requested.
91
92            ! * ' ( ) ; : @ & = + $ , / ? # [ ]
93
94   Unreserved Characters
95       The following characters are considered as Unreserved. They will not be
96       encoded
97
98           a-z
99           A-Z
100           0-9
101           - _ . ~
102

DEPENDENCIES

104       Encode
105

ACKNOWLEDGEMENTS

107       Gisle Aas for URI::Escape
108
109       David Nicol for Tie::UrlEncoder
110

SEE ALSO

112       RFC 3986 <http://tools.ietf.org/html/rfc3986>
113
114       URI::Escape
115
116       URI::Escape::XS
117
118       URI::Escape::JavaScript
119
120       Tie::UrlEncoder
121

BUGS AND LIMITATIONS

123       Please report any bugs or feature requests at
124       <https://github.com/mithun/perl-uri-encode/issues>
125

AUTHOR

127       Mithun Ayachit "mithun@cpan.org"
128

130       Copyright (c) 2014, Mithun Ayachit. All rights reserved.
131
132       This module is free software; you can redistribute it and/or modify it
133       under the same terms as Perl itself. See perlartistic.
134
135
136
137perl v5.36.0                      2023-01-20                    URI::Encode(3)
Impressum