Debian Codegraph @

README

raw
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