=encoding euc-jp =head1 NAME =begin original URI::Escape - Escape and unescape unsafe characters =end original URI::Escape - 安全でない文字のエスケープとアンエスケープ =head1 SYNOPSIS use URI::Escape; $safe = uri_escape("10% is enough\n"); $verysafe = uri_escape("foo", "\0-\377"); $str = uri_unescape($safe); =head1 DESCRIPTION =begin original This module provides functions to escape and unescape URI strings as defined by RFC 2396 (and updated by RFC 2732). A URI consists of a restricted set of characters, denoted as C in RFC 2396. The restricted set of characters consists of digits, letters, and a few graphic symbols chosen from those common to most of the character encodings and input facilities available to Internet users: =end original このモジュールは RFC 2396 で定義され(そして RFC 2732 で更新され)ている URI 文字列のエスケープとアンエスケープのための関数を提供します。 URI は RFC2396 で C として示された制限された文字集合で構成されます。 制限された文字集合は数字、文字そしてほとんどの文字エンコーディングと インターネットユーザが利用できる入力機能に共通なものから選ばれたいくつかの 記号で構成されます: "A" .. "Z", "a" .. "z", "0" .. "9", ";", "/", "?", ":", "@", "&", "=", "+", "$", ",", "[", "]", # reserved "-", "_", ".", "!", "~", "*", "'", "(", ")" =begin original In addition, any byte (octet) can be represented in a URI by an escape sequence: a triplet consisting of the character "%" followed by two hexadecimal digits. A byte can also be represented directly by a character, using the US-ASCII character for that octet (iff the character is part of C). =end original さらに、すべてのバイト(オクテット)は、"%"とその後に続く 2 文字の 16 進数の 3 文字からなるエスケープシーケンスによって URI で表すことが出来ます。 バイトは US-ASCII 文字を使って直接表すことも出来ます (もしその文字が C の一部であれば)。 =begin original Some of the C characters are I for use as delimiters or as part of certain URI components. These must be escaped if they are to be treated as ordinary data. Read RFC 2396 for further details. =end original C 文字のいくつかは区切り文字として、ある URI 構成要素の一部として 使うように予約されています。 通常のデータとして取り扱いたければ、これらはエスケープされなければなりません。 さらなる詳細については RFC 2396 を読んでください。 =begin original The functions provided (and exported by default) from this module are: =end original このモジュールから提供される(そしてデフォルトでエクスポートされる)関数は 以下の通りです: =over 4 =item uri_escape( $string ) =item uri_escape( $string, $unsafe ) =begin original Replaces each unsafe character in the $string with the corresponding escape sequence and returns the result. The $string argument should be a string of bytes. The uri_escape() function will croak if given a characters with code above 255. Use uri_escape_utf8() if you know you have such chars or/and want chars in the 128 .. 255 range treated as UTF-8. =end original $string の安全でないそれぞれの文字をエスケープシーケンスで置換し、 その結果を返します。 The $string argument should be a string of bytes. The uri_escape() function will croak if given a characters with code above 255. Use uri_escape_utf8() if you know you have such chars or/and want chars in the 128 .. 255 range treated as UTF-8. (TBT) =begin original The uri_escape() function takes an optional second argument that overrides the set of characters that are to be escaped. The set is specified as a string that can be used in a regular expression character class (between [ ]). E.g.: =end original uri_escape() 関数は、オプションでエスケープする文字集合を上書きする 2 番目の 引数を取ります。 集合は正規表現文字クラス([]の間)で使うことが出来る文字列として 指定されます。 例: "\x00-\x1f\x7f-\xff" # all control and hi-bit characters "a-z" # all lower case characters "^A-Za-z" # everything not a letter =begin original The default set of characters to be escaped is all those which are I part of the C character class shown above as well as the reserved characters. I.e. the default is: =end original エスケープされるデフォルトの文字セットは上記で示した C 文字 I<ではない> 部分のすべてと、予約されている文字です。 つまり、デフォルトは: "^A-Za-z0-9\-_.!~*'()" =item uri_escape_utf8( $string ) =item uri_escape_utf8( $string, $unsafe ) =begin original Works like uri_escape(), but will encode chars as UTF-8 before escaping them. This makes this function able do deal with characters with code above 255 in $string. Note that chars in the 128 .. 255 range will be escaped differently by this function compared to what uri_escape() would. For chars in the 0 .. 127 range there is no difference. =end original Works like uri_escape(), but will encode chars as UTF-8 before escaping them. This makes this function able do deal with characters with code above 255 in $string. Note that chars in the 128 .. 255 range will be escaped differently by this function compared to what uri_escape() would. For chars in the 0 .. 127 range there is no difference. (TBT) =begin original The call: =end original 以下の呼び出しは: $uri = uri_escape_utf8($string); =begin original will be the same as: =end original 以下と同じです: use Encode qw(encode); $uri = uri_escape(encode("UTF-8", $string)); =begin original but will even work for perl-5.6 for chars in the 128 .. 255 range. =end original しかし文字コード 128 ... 255 に対しても perl-5.6 で動作します。 =begin original Note: Javascript has a function called escape() that produce the sequence "%uXXXX" for chars in the 256 .. 65535 range. This function has really nothing to do with URI escaping but some folks got confused since it "does the right thing" in the 0 .. 255 range. Because of this you sometimes see "URIs" with these kind of escapes. The JavaScript encodeURI() function is similar to uri_escape_utf8(). =end original Note: Javascript has a function called escape() that produce the sequence "%uXXXX" for chars in the 256 .. 65535 range. This function has really nothing to do with URI escaping but some folks got confused since it "does the right thing" in the 0 .. 255 range. Because of this you sometimes see "URIs" with these kind of escapes. The JavaScript encodeURI() function is similar to uri_escape_utf8(). (TBT) =item uri_unescape($string,...) =begin original Returns a string with each %XX sequence replaced with the actual byte (octet). =end original それぞれの %XX シーケンスを実際のバイト(オクテット)に変換した文字列を 返します。 =begin original This does the same as: =end original これは以下のものと同じです: $string =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; =begin original but does not modify the string in-place as this RE would. Using the uri_unescape() function instead of the RE might make the code look cleaner and is a few characters less to type. =end original しかし、この正規表現がするように元の文字列は変更しません。 正規表現の代りに uri_unescape() 関数を使うと、コードは見やすくなり、 タイプする文字も少し減ります。 =begin original In a simple benchmark test I did, calling the function (instead of the inline RE above) if a few chars were unescaped was something like 40% slower, and something like 700% slower if none were. If you are going to unescape a lot of times it might be a good idea to inline the RE. =end original 簡単なベンチマークテストを行ったところ、アンエスケープする文字が 2, 3 であれば、(上記のインライン正規表現の代わりに)関数を呼び出すと 40% ほど遅くなりました。 暗エスケープする文字が何もなければ 700% ほど遅くなりました。 何回もアンエスケープするつもりであれば、インラインの正規表現を使うのは よい考えかもしれません。 =begin original If the uri_unescape() function is passed multiple strings, then each one is returned unescaped. =end original uri_unescape() 関数に複数の文字列を渡すと、それぞれがアンエスケープされて 返されます。 =back =begin original The module can also export the C<%escapes> hash, which contains the mapping from all 256 bytes to the corresponding escape codes. Lookup in this hash is faster than evaluating C each time. =end original モジュールは 256 バイト全てからの対応するエスケープコードへの マッピングが入った C<%escape> ハッシュもエクスポートします。 毎回 C を評価するよりも、このハッシュを 検索するほうが速くなります。 =head1 SEE ALSO L =head1 COPYRIGHT Copyright 1995-2004 Gisle Aas. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =begin meta Translate: Hippo2000 (1.04) Update: SHIRAKATA Kentaro (1.35) Status: in progress =end meta =cut