| 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
| |||||||||||||||||||||||||||||
| 171 | 43 | my $re; | |||||||||||||||||||||||||||
| 172 | 43 | ▶ | if (defined $patn) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 173 | 35 | ▶ | if (ref $patn eq 'Regexp') { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 174 | 2 | $text =~ s{($patn)}{ | |||||||||||||||||||||||||||
| 175 | 4 | ▶ | join('', map +($escapes{$_} || _fail_hi($_)), split //, "$1") | ||||||||||||||||||||||||||
|
Condition33%1/3
$URI::Escape::escapes{$_} || _fail_hi($_)
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($_)
| |||||||||||||||||||||||||||||
| 176 | }ge; | ||||||||||||||||||||||||||||
| 177 | 2 | return $text; | |||||||||||||||||||||||||||
| 178 | } | ||||||||||||||||||||||||||||
| 179 | 33 | $re = $subst{$patn}; | |||||||||||||||||||||||||||
| 180 | 33 | ▶ | if (!defined $re) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 188 | }ge; | ||||||||||||||||||||||||||||
| 189 | 16 | ▶ | eval { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 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)
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)
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
Condition66%2/3
@_ and wantarray
MC/DC50%1/2
@_ and wantarray
@_
wantarray
Truth table66%2/3
A and B
A= @_B= wantarray
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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; | |||||||||||||||||||||||||||