=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 3986. =end original このモジュールは RFC 3986 で定義されている URI 文字列のエスケープとアンエスケープのための関数を提供します。 =begin original A URI consists of a restricted set of characters. 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. They are made up of the "unreserved" and "reserved" character sets as defined in RFC 3986. =end original URI は制限された文字集合で構成されます。 制限された文字集合は数字、文字そしてほとんどの文字エンコーディングと インターネットユーザが利用できる入力機能に共通なものから選ばれたいくつかの 記号で構成されます。 これらは RFC 3986 で定義されている "unreserved" および "reserved" 文字集合からなります。 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 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. =end original さらに、すべてのバイト(オクテット)は、"%"とその後に続く 2 文字の 16 進数の 3 文字からなるエスケープシーケンスによって URI で表すことが出来ます。 バイトは US-ASCII 文字を使って直接表すことも出来ます。 =begin original Some of the 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 3986 for further details. =end original 文字のいくつかは区切り文字として、ある URI 構成要素の一部として 使うように予約されています。 通常のデータとして取り扱いたければ、これらはエスケープされなければなりません。 さらなる詳細については RFC 3986 を読んでください。 =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 の安全でないそれぞれの文字をエスケープシーケンスで置換し、 その結果を返します。 $string 引数はバイト文字列である必要があります。 uri_escape() 関数は、255 を超える符号位置を持つ文字が与えられると croak します。 そのような文字が含まれていることが分かっている場合、あるいは 128 ... 255 の範囲を UTF-8 として扱いたい場合は uri_escape_utf8() を使ってください。 =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 uri_escape() と同様に動作しますが、エスケープする前に、 文字を UTF-8 としてエンコードします。 これにより、$string に含まれている符号位置 255 を超える文字を 扱えるようになります。 128 .. 255 の範囲の文字は uri_escape() と異なる形でエスケープされることに 注意してください。 0 .. 127 の範囲の文字は変わりません。 =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 produces 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 encodeURIComponent() function is similar to uri_escape_utf8(). =end original 注意: JavaScript には、256 .. 65535 の範囲の文字に対して "%uXXXX" の 並びを生成する、escape() と呼ばれる関数があります。 この関数は URI エスケープとは全く関係ありませんが、 0 .. 255 の範囲では「正しいことを行う」ため、 一部の人は混乱しています。 このため、時々このようなエスケープをされた "URI" を目にすることがあります。 JavaScript の encodeURIComponent() 関数は uri_escape_utf8() と似ています。 =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: completed =end meta =cut