名前¶

URI::Escape - 安全でない文字のエスケープとアンエスケープ

概要¶

 use URI::Escape;
 $safe = uri_escape("10% is enough\n");
 $verysafe = uri_escape("foo", "\0-\377");
 $str  = uri_unescape($safe);

説明¶

このモジュールは RFC 3986 で定義されている URI 文字列のエスケープとアンエスケープのための関数を提供します。

URI は制限された文字集合で構成されます。 制限された文字集合は数字、文字そしてほとんどの文字エンコーディングと インターネットユーザが利用できる入力機能に共通なものから選ばれたいくつかの 記号で構成されます。 これらは RFC 3986 で定義されている "unreserved" および "reserved" 文字集合からなります。

   unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
   reserved      = ":" / "/" / "?" / "#" / "[" / "]" / "@"
                   "!" / "$" / "&" / "'" / "(" / ")"
                 / "*" / "+" / "," / ";" / "="

さらに、すべてのバイト(オクテット)は、"%"とその後に続く 2 文字の 16 進数の 3 文字からなるエスケープシーケンスによって URI で表すことが出来ます。 バイトは US-ASCII 文字を使って直接表すことも出来ます。

文字のいくつかは区切り文字として、ある URI 構成要素の一部として 使うように予約されています。 通常のデータとして取り扱いたければ、これらはエスケープされなければなりません。 さらなる詳細については RFC 3986 を読んでください。

このモジュールから提供される(そしてデフォルトでエクスポートされる)関数は 以下の通りです:

uri_escape( $string )

uri_escape( $string, $unsafe )

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.

$string の安全でないそれぞれの文字をエスケープシーケンスで置換し、 その結果を返します。 $string 引数はバイト文字列である必要があります。 uri_escape() 関数は、255 を超える符号位置を持つ文字が与えられると croak します。 そのような文字が含まれていることが分かっている場合、あるいは 128 ... 255 の範囲を UTF-8 として扱いたい場合は uri_escape_utf8() を使ってください。

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.:

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

The default set of characters to be escaped is all those which are not part of the unreserved character class shown above as well as the reserved characters. I.e. the default is:

エスケープされるデフォルトの文字セットは上記で示した unreserved 文字 ではない 部分のすべてと、予約されている文字です。 つまり、デフォルトは:

    "^A-Za-z0-9\-\._~"

uri_escape_utf8( $string )

uri_escape_utf8( $string, $unsafe )

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.

uri_escape() と同様に動作しますが、エスケープする前に、 文字を UTF-8 としてエンコードします。 これにより、$string に含まれている符号位置 255 を超える文字を 扱えるようになります。 128 .. 255 の範囲の文字は uri_escape() と異なる形でエスケープされることに 注意してください。 0 .. 127 の範囲の文字は変わりません。

The call:

以下の呼び出しは:

    $uri = uri_escape_utf8($string);

will be the same as:

以下と同じです:

    use Encode qw(encode);
    $uri = uri_escape(encode("UTF-8", $string));

but will even work for perl-5.6 for chars in the 128 .. 255 range.

しかし文字コード 128 ... 255 に対しても perl-5.6 で動作します。

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().

注意: JavaScript には、256 .. 65535 の範囲の文字に対して "%uXXXX" の 並びを生成する、escape() と呼ばれる関数があります。 この関数は URI エスケープとは全く関係ありませんが、 0 .. 255 の範囲では「正しいことを行う」ため、 一部の人は混乱しています。 このため、時々このようなエスケープをされた "URI" を目にすることがあります。 JavaScript の encodeURIComponent() 関数は uri_escape_utf8() と似ています。

uri_unescape($string,...)

Returns a string with each %XX sequence replaced with the actual byte (octet).

それぞれの %XX シーケンスを実際のバイト(オクテット)に変換した文字列を 返します。

This does the same as:

これは以下のものと同じです:

   $string =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;

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.

しかし、この正規表現がするように元の文字列は変更しません。 正規表現の代りに uri_unescape() 関数を使うと、コードは見やすくなり、 タイプする文字も少し減ります。

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.

簡単なベンチマークテストを行ったところ、アンエスケープする文字が 2, 3 であれば、(上記のインライン正規表現の代わりに)関数を呼び出すと 40% ほど遅くなりました。 暗エスケープする文字が何もなければ 700% ほど遅くなりました。 何回もアンエスケープするつもりであれば、インラインの正規表現を使うのは よい考えかもしれません。

If the uri_unescape() function is passed multiple strings, then each one is returned unescaped.

uri_unescape() 関数に複数の文字列を渡すと、それぞれがアンエスケープされて 返されます。

モジュールは 256 バイト全てからの対応するエスケープコードへの マッピングが入った %escape ハッシュもエクスポートします。 毎回 sprintf("%%%02X", ord($byte)) を評価するよりも、このハッシュを 検索するほうが速くなります。

SEE ALSO¶

URI

コピーライト¶

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.