1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
=head1 NAME
URL::Encode - Encoding and decoding of C<application/x-www-form-urlencoded> encoding.
=head1 SYNOPSIS
$octets = url_decode($octets);
$string = url_decode_utf8($octets);
$octets = url_encode($octets);
$octets = url_encode_utf8($string);
$params = url_params_flat($octets [, $utf8 = false]);
$params = url_params_mixed($octets [, $utf8 = false]);
$params = url_params_multi($octets [, $utf8 = false]);
url_params_each($octets, $callback [, $utf8 = false]);
=head1 DESCRIPTION
This module provides functions to encode and decode strings into and from the
C<application/x-www-form-urlencoded> encoding.
The C<application/x-www-form-urlencoded> format encodes a ordered data
sets of pairs consisting of a name and a value, with pairs separated by
ampersand or semicolon and names and values separated by the equal sign.
Space characters are replaced with plus sign and any characters not in
the unreserved character set is encoded using the percent-encoding scheme
also used for resource identifiers. A percent-encoded octet is encoded as
a character triplet, consisting of the percent character "%" followed by
the two hexadecimal digits representing that octet's numeric value.
The unreserved character set includes the uppercase and lowercase letters,
decimal digits, hyphen, period, underscore, and tilde.
ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789
- . _ ~
=head1 FUNCTIONS
=head2 url_decode
$octets = url_decode($octets);
Returns a decoded representation of the given URL-encoded C<$octets> as an
octet string.
=head2 url_decode_utf8
$string = url_decode_utf8($octets);
Returns a decoded representation of the given URL-encoded C<$octets> in
UTF-8 encoding as a character string.
=head2 url_encode
$octets = url_encode($octets);
Returns a URL-encoded representation of the given C<$octets> as an octet
string.
=head2 url_encode_utf8
$octets = url_encode_utf8($string);
Returns a URL-encoded representation of C<$string> in UTF-8 encoding as an
octet string.
=head2 url_params_flat
$params = url_params_flat($octets);
$params = url_params_flat($octets, $utf8);
Parses a URL-encoded data set of name/value pairs from the given octets.
Returns an ARRAY reference containing the URL-decoded name/value pairs in order.
$params = url_params_flat('foo=A&foo=B&bar=C');
$params; # [ foo => 'A', foo => 'B', bar => 'C' ]
=head2 url_params_mixed
$params = url_params_mixed($octets);
$params = url_params_mixed($octets, $utf8);
Parses a URL-encoded data set of name/value pairs from the given octets.
Returns a HASH reference containing the URL-decoded name/value pairs. Multiple
occurrences of a parameter will result in an ARRAY reference holding all
the values for that parameter in order.
$params = url_params_mixed('foo=A&foo=B&bar=C');
$params; # { foo => [ 'A', 'B' ], bar => 'C' }
=head2 url_params_multi
$params = url_params_multi($octets);
$params = url_params_multi($octets, $utf8);
Parses a URL-encoded data set of name/value pairs from the given octets.
Returns a HASH reference containing the URL-decoded name/value pairs. Values
are stored in an ARRAY reference.
$params = url_params_multi('foo=A&foo=B&bar=C');
$params; # { foo => [ 'A', 'B' ], bar => [ 'C' ] }
=head2 url_params_each
url_params_each($octets, $callback);
url_params_each($octets, $callback, $utf8);
Parses a URL-encoded data set of name/value pairs from the given octets.
Invokes the given callback for each URL-decoded name/value pair.
$callback = sub {
my ($name, $value) = @_;
};
url_params_each($octets, $callback);
=head1 EXPORTS
None by default. All functions can be exported using the C<:all> tag or individually.
=head1 DIAGNOSTICS
=over 4
=item B<(F)> Usage: %s
Subroutine called with wrong number of arguments.
=item B<(F)> Wide character in octet string
=item B<(F)> Malformed UTF-8 in URL-decoded octets
=back
=head1 PERFORMANCE
The L<URL::Encode::XS> module provides faster C/XS implementations of
the functions found in this module. This module will automatically use
L<URL::Encode::XS> if it's installed.
Benchmarking url_decode() PP vs XS:
Rate PP XS
PP 507520/s -- -92%
XS 6389812/s 1159% --
Benchmarking url_encode() PP vs XS:
Rate PP XS
PP 119866/s -- -98%
XS 7214089/s 5918% --
Benchmarking url_params_mixed() PP vs XS:
Rate PP XS
PP 4450/s -- -95%
XS 95015/s 2035% --
Benchmarking URL::Encode::XS vs CGI::Deurl::XS
Rate CGI::Deurl::XS URL::Encode::XS
CGI::Deurl::XS 51932/s -- -48%
URL::Encode::XS 99444/s 91% --
=head1 SEE ALSO
=over 4
=item L<URL::Encode::XS>
XS implementation of C<URL::Encode>.
=item L<CGI::Deurl::XS>
=back
=head1 SUPPORT
=head2 BUGS
Please report any bugs by email to C<bug-url-encode at rt.cpan.org>, or
through the web interface at L<http://rt.cpan.org/Public/Dist/Display.html?Name=URL-Encode>.
You will be automatically notified of any progress on the request by the system.
=head2 SOURCE CODE
This is open source software. The code repository is available for public
review and contribution under the terms of the license.
L<http://github.com/chansen/p5-url-encode>
git clone http://github.com/chansen/p5-url-encode
=head1 AUTHOR
Christian Hansen C<chansen@cpan.org>
=head1 COPYRIGHT
Copyright 2011-2014 by Christian Hansen.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
|
