URI/Escape.pm

filter: Statementstmt 100% 66 / 66 Branchbran 90.9% 20 / 22 Conditioncond 55.5% 5 / 9 MC/DCmcdc 16.6% 1 / 6 Subroutinesub 100% 10 / 10 Podpod 75.0% 3 / 4 totaltotal 89.7% 105 / 117 CC 16 SCAR 17.2
CC
16
Cov
94%
uri_escape
10.1
uri_unescape
5.0
uri_escape_utf8
2.0
CRAP 5.6
« URI/file/Unix.pm ↑ Summary URI/file/Base.pm »
1 package URI::Escape;
2  
3 61 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 61 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 =head1 NAME
7  
8 URI::Escape - Percent-encode and percent-decode unsafe characters
9  
10 =head1 SYNOPSIS
11  
12 use URI::Escape;
13 $safe = uri_escape("10% is enough\n");
14 $verysafe = uri_escape("foo", "\0-\377");
15 $str = uri_unescape($safe);
16  
17 =head1 DESCRIPTION
18  
19 This module provides functions to percent-encode and percent-decode URI strings as
20 defined by RFC 3986. Percent-encoding URI's is informally called "URI escaping".
21 This is the terminology used by this module, which predates the formalization of the
22 terms by the RFC by several years.
23  
24 A URI consists of a restricted set of characters. The restricted set
25 of characters consists of digits, letters, and a few graphic symbols
26 chosen from those common to most of the character encodings and input
27 facilities available to Internet users. They are made up of the
28 "unreserved" and "reserved" character sets as defined in RFC 3986.
29  
30 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
31 reserved = ":" / "/" / "?" / "#" / "[" / "]" / "@"
32 "!" / "$" / "&" / "'" / "(" / ")"
33 / "*" / "+" / "," / ";" / "="
34  
35 In addition, any byte (octet) can be represented in a URI by an escape
36 sequence: a triplet consisting of the character "%" followed by two
37 hexadecimal digits. A byte can also be represented directly by a
38 character, using the US-ASCII character for that octet.
39  
40 Some of the characters are I<reserved> for use as delimiters or as
41 part of certain URI components. These must be escaped if they are to
42 be treated as ordinary data. Read RFC 3986 for further details.
43  
44 The functions provided (and exported by default) from this module are:
45  
46 =over 4
47  
48 =item uri_escape( $string )
49  
50 =item uri_escape( $string, $unsafe )
51  
52 Replaces each unsafe character in the $string with the corresponding
53 escape sequence and returns the result. The $string argument should
54 be a string of bytes. The uri_escape() function will croak if given a
55 characters with code above 255. Use uri_escape_utf8() if you know you
56 have such chars or/and want chars in the 128 .. 255 range treated as
57 UTF-8.
58  
59 The uri_escape() function takes an optional second argument that
60 overrides the set of characters that are to be escaped. The set is
61 specified as a string that can be used in a regular expression
62 character class (between [ ]). E.g.:
63  
64 "\x00-\x1f\x7f-\xff" # all control and hi-bit characters
65 "a-z" # all lower case characters
66 "^A-Za-z" # everything not a letter
67  
68 The default set of characters to be escaped is all those which are
69 I<not> part of the C<unreserved> character class shown above as well
70 as the reserved characters. I.e. the default is:
71  
72 "^A-Za-z0-9\-\._~"
73  
74 The second argument can also be specified as a regular expression object:
75  
76 qr/[^A-Za-z]/
77  
78 Any strings matched by this regular expression will have all of their
79 characters escaped.
80  
81 =item uri_escape_utf8( $string )
82  
83 =item uri_escape_utf8( $string, $unsafe )
84  
85 Works like uri_escape(), but will encode chars as UTF-8 before
86 escaping them. This makes this function able to deal with characters
87 with code above 255 in $string. Note that chars in the 128 .. 255
88 range will be escaped differently by this function compared to what
89 uri_escape() would. For chars in the 0 .. 127 range there is no
90 difference.
91  
92 Equivalent to:
93  
94 utf8::encode($string);
95 my $uri = uri_escape($string);
96  
97 Note: JavaScript has a function called escape() that produces the
98 sequence "%uXXXX" for chars in the 256 .. 65535 range. This function
99 has really nothing to do with URI escaping but some folks got confused
100 since it "does the right thing" in the 0 .. 255 range. Because of
101 this you sometimes see "URIs" with these kind of escapes. The
102 JavaScript encodeURIComponent() function is similar to uri_escape_utf8().
103  
104 =item uri_unescape($string,...)
105  
106 Returns a string with each %XX sequence replaced with the actual byte
107 (octet).
108  
109 This does the same as:
110  
111 $string =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
112  
113 but does not modify the string in-place as this RE would. Using the
114 uri_unescape() function instead of the RE might make the code look
115 cleaner and is a few characters less to type.
116  
117 In a simple benchmark test I did,
118 calling the function (instead of the inline RE above) if a few chars
119 were unescaped was something like 40% slower, and something like 700% slower if none were. If
120 you are going to unescape a lot of times it might be a good idea to
121 inline the RE.
122  
123 If the uri_unescape() function is passed multiple strings, then each
124 one is returned unescaped.
125  
126 =back
127  
128 The module can also export the C<%escapes> hash, which contains the
129 mapping from all 256 bytes to the corresponding escape codes. Lookup
130 in this hash is faster than evaluating C<sprintf("%%%02X", ord($byte))>
131 each time.
132  
133 =head1 SEE ALSO
134  
135 L<URI>
136  
137  
138 =head1 COPYRIGHT
139  
140 Copyright 1995-2004 Gisle Aas.
141  
142 This program is free software; you can redistribute it and/or modify
143 it under the same terms as Perl itself.
144  
145 =cut
146  
147 61 ▶use Exporter 5.57 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
148 61 our %escapes;
149 61 our @EXPORT = qw(uri_escape uri_unescape uri_escape_utf8);
150 61 our @EXPORT_OK = qw(%escapes);
151  
152 61 our $VERSION = '5.40';
153  
154 61 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
155  
156 # Build a char->hex map
157 61 for (0 .. 255) {
158 15616 $escapes{chr($_)} = sprintf("%%%02X", $_);
159 }
160  
161 61 my %subst; # compiled patterns
162  
163 61 my %Unsafe = (
164 RFC2732 => qr/[^A-Za-z0-9\-_.!~*'()]/,
165 RFC3986 => qr/[^A-Za-z0-9\-\._~]/,
166 );
167  
168 44 ▶sub uri_escape {
Subroutine uri_escape: called CC=10 SCAR=23.1
Pod documented
169 44 my ($text, $patn) = @_;
170 44 ▶ return undef unless defined $text;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text 1 43 44
171 43 my $re;
172 43 ▶ if (defined $patn) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $patn) { } 35 8 43
173 35 ▶ if (ref $patn eq 'Regexp') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $patn eq "Regexp") 2 33 35
174 2 $text =~ s{($patn)}{
175 4 ▶ join('', map +($escapes{$_} || _fail_hi($_)), split //, "$1")
Condition33%1/3
$URI::Escape::escapes{$_} || _fail_hi($_)
l!l&&r!l&&!r
600
MC/DC0%0/2
$URI::Escape::escapes{$_} || _fail_hi($_)
$URI::Escape::escapes{$_} _fail_hi($_)
Truth table33%1/3
A || B
A= $URI::Escape::escapes{$_}B= _fail_hi($_)
ABresult
1X1
011
000
176 }ge;
177 2 return $text;
178 }
179 33 $re = $subst{$patn};
180 33 ▶ if (!defined $re) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $re) 16 17 33
181 16 $re = $patn;
182  
183 # we need to escape the [] characters, except for those used in
184 # posix classes. if they are prefixed by a backslash, allow them
185 # through unmodified.
186 16 $re =~ s{(\[:\w+:\])|(\\)?([\[\]]|\\\z)}{
187 13 ▶ defined $1 ? $1 : defined $2 ? "$2$3" : "\\$3"
Branch: 2 branches
BranchTrueFalseTotal
defined $1 ? : 2 11 13
defined $2 ? : 0 11 11
188 }ge;
189 16 ▶ eval {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { BEGIN {${^WARNING_BITS} = "\x55\x55\x55\x55\x55\x54\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55"} $re = ($subst{$patn} = qr/[$re]/); 1 } } or Carp::croak("uri_escape: $@") 15 1 16
190 # disable the warnings here, since they will trigger later
191 # when used, and we only want them to appear once per call,
192 # but every time the same pattern is used.
193 61 ▶ no warnings 'regexp';
Subroutine BEGIN: called CC=1 SCAR=0.0
194 16 $re = $subst{$patn} = qr{[$re]};
195 15 1;
196 } or Carp::croak("uri_escape: $@");
197 }
198 }
199 else {
200 8 $re = $Unsafe{RFC3986};
201 }
202 40 ▶ $text =~ s/($re)/$escapes{$1} || _fail_hi($1)/ge;
Condition66%2/3
$URI::Escape::escapes{$1} || _fail_hi($1)
l!l&&r!l&&!r
26410
MC/DC0%0/2
$URI::Escape::escapes{$1} || _fail_hi($1)
$URI::Escape::escapes{$1} _fail_hi($1)
Truth table33%1/3
A || B
A= $URI::Escape::escapes{$1}B= _fail_hi($1)
ABresult
1X1
011
000
203 39 $text;
204 }
205  
206 1 ▶sub _fail_hi {
Subroutine _fail_hi: called CC=1 SCAR=0.0
207 1 my $chr = shift;
208 1 Carp::croak(sprintf "Can't escape \\x{%04X}, try uri_escape_utf8() instead",
209 ord($chr));
210 }
211  
212 2 ▶sub uri_escape_utf8 {
Subroutine uri_escape_utf8: called CC=2 SCAR=7.0
Pod documented
213 2 my $text = shift;
214 2 ▶ return undef unless defined $text;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text 0 2 2
215 2 utf8::encode($text);
216 2 return uri_escape($text, @_);
217 }
218  
219 3220 ▶sub uri_unescape {
Subroutine uri_unescape: called CC=5 SCAR=16.1
Pod documented
220  
221 # Note from RFC1630: "Sequences which start with a percent sign
222 # but are not followed by two hexadecimal characters are reserved
223 # for future extension"
224 3220 my $str = shift;
225 3220 ▶ if (@_ && wantarray) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_ and wantarray) 1 3219 3220
Condition66%2/3
@_ and wantarray
!ll&&!rl&&r
321901
MC/DC50%1/2
@_ and wantarray
@_ wantarray
Truth table66%2/3
A and B
A= @_B= wantarray
ABresult
0X0
100
111
226  
227 # not executed for the common case of a single argument
228 1 my @str = ($str, @_); # need to copy
229 1 for (@str) {
230 3 s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
231 }
232 1 return @str;
233 }
234 3219 ▶ $str =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg if defined $str;
Branch: 1 branch
BranchTrueFalseTotal
if defined $str 3218 1 3219
235 3219 $str;
236 }
237  
238 # XXX FIXME escape_char is buggy as it assigns meaning to the string's storage format.
239 672 ▶sub escape_char {
Subroutine escape_char: called CC=2 SCAR=6.9
Pod undocumented
240  
241 # Old versions of utf8::is_utf8() didn't properly handle magical vars (e.g. $1).
242 # The following forces a fetch to occur beforehand.
243 672 () = substr($_[0], 0, 0);
244  
245 672 ▶ if (utf8::is_utf8($_[0])) {
Branch: 1 branch
BranchTrueFalseTotal
if (utf8::is_utf8($_[0])) 134 538 672
246 134 my $s = shift;
247 134 utf8::encode($s);
248 134 unshift(@_, $s);
249 }
250  
251 672 return join '', @URI::Escape::escapes{split //, $_[0]};
252 }
253  
254 61 1;
« URI/file/Unix.pm ↑ Summary URI/file/Base.pm »