URI-1.54 > 1.35 との差分

URI::Escape 1.35 と 1.54 の差分

11
22=encoding euc-jp
33
44=head1 NAME
55
66=begin original
77
88URI::Escape - Escape and unescape unsafe characters
99
1010=end original
1111
1212URI::Escape - 安全でない文字のエスケープとアンエスケープ
1313
1414=head1 SYNOPSIS
1515
1616 use URI::Escape;
1717 $safe = uri_escape("10% is enough\n");
1818 $verysafe = uri_escape("foo", "\0-\377");
1919 $str = uri_unescape($safe);
2020
2121=head1 DESCRIPTION
2222
2323=begin original
2424
2525This module provides functions to escape and unescape URI strings as
26defined by RFC 2396 (and updated by RFC 2732).
26defined by RFC 3986.
27A URI consists of a restricted set of characters,
28denoted as C<uric> in RFC 2396. The restricted set of characters
29consists of digits, letters, and a few graphic symbols chosen from
30those common to most of the character encodings and input facilities
31available to Internet users:
3227
3328=end original
3429
35このモジュールは RFC 2396 で定義され(そして RFC 2732 で更新され)ている
30このモジュールは RFC 3986 で定義されている
3631URI 文字列のエスケープとアンエスケープのための関数を提供します。
37URI は RFC2396 で C<uric> として示された制限された文字集合で構成されます。
33=begin original
34
35A URI consists of a restricted set of characters. The restricted set
36of characters consists of digits, letters, and a few graphic symbols
37chosen from those common to most of the character encodings and input
38facilities available to Internet users. They are made up of the
39"unreserved" and "reserved" character sets as defined in RFC 3986.
40
41=end original
42
43URI は制限された文字集合で構成されます。
3844制限された文字集合は数字、文字そしてほとんどの文字エンコーディングと
3945インターネットユーザが利用できる入力機能に共通なものから選ばれたいくつかの
40記号で構成されます:
46記号で構成されます。
47これらは RFC 3986 で定義されている "unreserved" および "reserved"
48文字集合からなります。
4149
42 "A" .. "Z", "a" .. "z", "0" .. "9",
50 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
43 ";", "/", "?", ":", "@", "&", "=", "+", "$", ",", "[", "]", # reserved
51 reserved = ":" / "/" / "?" / "#" / "[" / "]" / "@"
44 "-", "_", ".", "!", "~", "*", "'", "(", ")"
52 "!" / "$" / "&" / "'" / "(" / ")"
53 / "*" / "+" / "," / ";" / "="
4554
4655=begin original
4756
4857In addition, any byte (octet) can be represented in a URI by an escape
4958sequence: a triplet consisting of the character "%" followed by two
5059hexadecimal digits. A byte can also be represented directly by a
51character, using the US-ASCII character for that octet (iff the
60character, using the US-ASCII character for that octet.
52character is part of C<uric>).
5361
5462=end original
5563
5664さらに、すべてのバイト(オクテット)は、"%"とその後に続く 2 文字の 16 進数の
57653 文字からなるエスケープシーケンスによって URI で表すことが出来ます。
58バイトは US-ASCII 文字を使って直接表すことも出来ます
66バイトは US-ASCII 文字を使って直接表すことも出来ます。
59(もしその文字が C<uric> の一部であれば)。
6067
6168=begin original
6269
63Some of the C<uric> characters are I<reserved> for use as delimiters
70Some of the characters are I<reserved> for use as delimiters or as
64or as part of certain URI components. These must be escaped if they are
71part of certain URI components. These must be escaped if they are to
65to be treated as ordinary data. Read RFC 2396 for further details.
72be treated as ordinary data. Read RFC 3986 for further details.
6673
6774=end original
6875
69C<uric> 文字のいくつかは区切り文字として、ある URI 構成要素の一部として
76文字のいくつかは区切り文字として、ある URI 構成要素の一部として
7077使うように予約されています。
7178通常のデータとして取り扱いたければ、これらはエスケープされなければなりません。
72さらなる詳細については RFC 2396 を読んでください。
79さらなる詳細については RFC 3986 を読んでください。
7380
7481=begin original
7582
7683The functions provided (and exported by default) from this module are:
7784
7885=end original
7986
8087このモジュールから提供される(そしてデフォルトでエクスポートされる)関数は
8188以下の通りです:
8289
8390=over 4
8491
8592=item uri_escape( $string )
8693
8794=item uri_escape( $string, $unsafe )
8895
8996=begin original
9097
9198Replaces each unsafe character in the $string with the corresponding
9299escape sequence and returns the result. The $string argument should
93100be a string of bytes. The uri_escape() function will croak if given a
94101characters with code above 255. Use uri_escape_utf8() if you know you
95102have such chars or/and want chars in the 128 .. 255 range treated as
96103UTF-8.
97104
98105=end original
99106
100107$string の安全でないそれぞれの文字をエスケープシーケンスで置換し、
101108その結果を返します。
102The $string argument should
109$string 引数はバイト文字列である必要があります。
103be a string of bytes. The uri_escape() function will croak if given a
110uri_escape() 関数は、255 を超える符号位置を持つ文字が与えられると
104characters with code above 255. Use uri_escape_utf8() if you know you
111croak します。
105have such chars or/and want chars in the 128 .. 255 range treated as
112そのような文字が含まれていることが分かっている場合、あるいは
106UTF-8.
113128 ... 255 の範囲を UTF-8 として扱いたい場合は
107(TBT)
114uri_escape_utf8() を使ってください。
108115
109116=begin original
110117
111118The uri_escape() function takes an optional second argument that
112119overrides the set of characters that are to be escaped. The set is
113120specified as a string that can be used in a regular expression
114121character class (between [ ]). E.g.:
115122
116123=end original
117124
118125uri_escape() 関数は、オプションでエスケープする文字集合を上書きする 2 番目の
119126引数を取ります。
120127集合は正規表現文字クラス([]の間)で使うことが出来る文字列として
121128指定されます。
122129例:
123130
124131 "\x00-\x1f\x7f-\xff" # all control and hi-bit characters
125132 "a-z" # all lower case characters
126133 "^A-Za-z" # everything not a letter
127134
128135=begin original
129136
130137The default set of characters to be escaped is all those which are
131I<not> part of the C<uric> character class shown above as well as the
138I<not> part of the C<unreserved> character class shown above as well
132reserved characters. I.e. the default is:
139as the reserved characters. I.e. the default is:
133140
134141=end original
135142
136エスケープされるデフォルトの文字セットは上記で示した C<uric> 文字 I<ではない>
143エスケープされるデフォルトの文字セットは上記で示した
137部分のすべてと、予約されている文字です。
144C<unreserved> 文字 I<ではない> 部分のすべてと、予約されている文字です。
138145つまり、デフォルトは:
139146
140 "^A-Za-z0-9\-_.!~*'()"
147 "^A-Za-z0-9\-\._~"
141148
142149=item uri_escape_utf8( $string )
143150
144151=item uri_escape_utf8( $string, $unsafe )
145152
146153=begin original
147154
148155Works like uri_escape(), but will encode chars as UTF-8 before
149156escaping them. This makes this function able do deal with characters
150157with code above 255 in $string. Note that chars in the 128 .. 255
151158range will be escaped differently by this function compared to what
152159uri_escape() would. For chars in the 0 .. 127 range there is no
153160difference.
154161
155162=end original
156163
157Works like uri_escape(), but will encode chars as UTF-8 before
164uri_escape() と同様に動作しますが、エスケープする前に、
158escaping them. This makes this function able do deal with characters
165文字を UTF-8 としてエンコードします。
159with code above 255 in $string. Note that chars in the 128 .. 255
166これにより、$string に含まれている符号位置 255 を超える文字を
160range will be escaped differently by this function compared to what
167扱えるようになります。
161uri_escape() would. For chars in the 0 .. 127 range there is no
168128 .. 255 の範囲の文字は uri_escape() と異なる形でエスケープされることに
162difference.
169注意してください。
163(TBT)
1700 .. 127 の範囲の文字は変わりません。
164171
165172=begin original
166173
167174The call:
168175
169176=end original
170177
171178以下の呼び出しは:
172179
173180 $uri = uri_escape_utf8($string);
174181
175182=begin original
176183
177184will be the same as:
178185
179186=end original
180187
181188以下と同じです:
182189
183190 use Encode qw(encode);
184191 $uri = uri_escape(encode("UTF-8", $string));
185192
186193=begin original
187194
188195but will even work for perl-5.6 for chars in the 128 .. 255 range.
189196
190197=end original
191198
192199しかし文字コード 128 ... 255 に対しても perl-5.6 で動作します。
193200
194201=begin original
195202
196Note: Javascript has a function called escape() that produce the
203Note: JavaScript has a function called escape() that produces the
197204sequence "%uXXXX" for chars in the 256 .. 65535 range. This function
198205has really nothing to do with URI escaping but some folks got confused
199206since it "does the right thing" in the 0 .. 255 range. Because of
200207this you sometimes see "URIs" with these kind of escapes. The
201JavaScript encodeURI() function is similar to uri_escape_utf8().
208JavaScript encodeURIComponent() function is similar to uri_escape_utf8().
202209
203210=end original
204211
205Note: Javascript has a function called escape() that produce the
212注意: JavaScript には、256 .. 65535 の範囲の文字に対して "%uXXXX" の
206sequence "%uXXXX" for chars in the 256 .. 65535 range. This function
213並びを生成する、escape() と呼ばれる関数があります。
207has really nothing to do with URI escaping but some folks got confused
214この関数は URI エスケープとは全く関係ありませんが、
208since it "does the right thing" in the 0 .. 255 range. Because of
2150 .. 255 の範囲では「正しいことを行う」ため、
209this you sometimes see "URIs" with these kind of escapes. The
216一部の人は混乱しています。
210JavaScript encodeURI() function is similar to uri_escape_utf8().
217このため、時々このようなエスケープをされた "URI" を目にすることがあります。
211(TBT)
218JavaScript の encodeURIComponent() 関数は uri_escape_utf8() と似ています。
212219
213220=item uri_unescape($string,...)
214221
215222=begin original
216223
217224Returns a string with each %XX sequence replaced with the actual byte
218225(octet).
219226
220227=end original
221228
222229それぞれの %XX シーケンスを実際のバイト(オクテット)に変換した文字列を
223230返します。
224231
225232=begin original
226233
227234This does the same as:
228235
229236=end original
230237
231238これは以下のものと同じです:
232239
233240 $string =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
234241
235242=begin original
236243
237244but does not modify the string in-place as this RE would. Using the
238245uri_unescape() function instead of the RE might make the code look
239246cleaner and is a few characters less to type.
240247
241248=end original
242249
243250しかし、この正規表現がするように元の文字列は変更しません。
244251正規表現の代りに uri_unescape() 関数を使うと、コードは見やすくなり、
245252タイプする文字も少し減ります。
246253
247254=begin original
248255
249256In a simple benchmark test I did,
250257calling the function (instead of the inline RE above) if a few chars
251258were unescaped was something like 40% slower, and something like 700% slower if none were. If
252259you are going to unescape a lot of times it might be a good idea to
253260inline the RE.
254261
255262=end original
256263
257264簡単なベンチマークテストを行ったところ、アンエスケープする文字が
2582652, 3 であれば、(上記のインライン正規表現の代わりに)関数を呼び出すと
25926640% ほど遅くなりました。
260267暗エスケープする文字が何もなければ 700% ほど遅くなりました。
261268何回もアンエスケープするつもりであれば、インラインの正規表現を使うのは
262269よい考えかもしれません。
263270
264271=begin original
265272
266273If the uri_unescape() function is passed multiple strings, then each
267274one is returned unescaped.
268275
269276=end original
270277
271278uri_unescape() 関数に複数の文字列を渡すと、それぞれがアンエスケープされて
272279返されます。
273280
274281=back
275282
276283=begin original
277284
278285The module can also export the C<%escapes> hash, which contains the
279286mapping from all 256 bytes to the corresponding escape codes. Lookup
280287in this hash is faster than evaluating C<sprintf("%%%02X", ord($byte))>
281288each time.
282289
283290=end original
284291
285292モジュールは 256 バイト全てからの対応するエスケープコードへの
286293マッピングが入った C<%escape> ハッシュもエクスポートします。
287294毎回 C<sprintf("%%%02X", ord($byte))> を評価するよりも、このハッシュを
288295検索するほうが速くなります。
289296
290297=head1 SEE ALSO
291298
292299L<URI>
293300
294301=head1 COPYRIGHT
295302
296303Copyright 1995-2004 Gisle Aas.
297304
298305This program is free software; you can redistribute it and/or modify
299306it under the same terms as Perl itself.
300307
301308=begin meta
302309
303310Translate: Hippo2000 <GCD00051@nifty.ne.jp> (1.04)
304Update: SHIRAKATA Kentaro <argrath@ub32.org> (1.35)
311Update: SHIRAKATA Kentaro <argrath@ub32.org> (1.35-)
305Status: in progress
312Status: completed
306313
307314=end meta
308315
309316=cut
Powered by Amon2, 翻訳, サイト. Operated by Japan Perl Association