home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _8986c60cb05dccbb4290d38e4ebbeaad < prev    next >
Text File  |  2000-03-23  |  5KB  |  126 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>URI::Escape - Escape and unescape unsafe characters</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> URI::Escape - Escape and unescape unsafe characters</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  26.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  27. </UL>
  28. <!-- INDEX END -->
  29.  
  30. <HR>
  31. <P>
  32. <H1><A NAME="name">NAME</A></H1>
  33. <P>URI::Escape - Escape and unescape unsafe characters</P>
  34. <P>
  35. <HR>
  36. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  37. <UL>
  38. <LI>Linux</LI>
  39. <LI>Solaris</LI>
  40. <LI>Windows</LI>
  41. </UL>
  42. <HR>
  43. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  44. <PRE>
  45.  use URI::Escape;
  46.  $safe = uri_escape("10% is enough\n");
  47.  $verysafe = uri_escape("foo", "\0-\377");
  48.  $str  = uri_unescape($safe);</PRE>
  49. <P>
  50. <HR>
  51. <H1><A NAME="description">DESCRIPTION</A></H1>
  52. <P>This module provides functions to escape and unescape URI strings as
  53. defined by RFC 2396.  URIs consist of a restricted set of characters,
  54. denoted as <CODE>uric</CODE> in RFC 2396.  The restricted set of characters
  55. consists of digits, letters, and a few graphic symbols chosen from
  56. those common to most of the character encodings and input facilities
  57. available to Internet users:</P>
  58. <PRE>
  59.   "A" .. "Z", "a" .. "z", "0" .. "9",
  60.   ";", "/", "?", ":", "@", "&", "=", "+", "$", ",",   # reserved
  61.   "-", "_", ".", "!", "~", "*", "'", "(", ")"</PRE>
  62. <P>In addition any byte (octet) can be represented in a URI by an escape
  63. sequence; a triplet consisting of the character ``%'' followed by two
  64. hexadecimal digits.  Bytes can also be represented directly by a
  65. character using the US-ASCII character for that octet (iff the
  66. character is part of <CODE>uric</CODE>).</P>
  67. <P>Some of the <CODE>uric</CODE> characters are <EM>reserved</EM> for use as delimiters
  68. or as part of certain URI components.  These must be escaped if they are
  69. to be treated as ordinary data.  Read RFC 2396 for further details.</P>
  70. <P>The functions provided (and exported by default) from this module are:</P>
  71. <DL>
  72. <DT><STRONG><A NAME="item_uri_escape">uri_escape($string, [$unsafe])</A></STRONG><BR>
  73. <DD>
  74. This function replaces all unsafe characters in the $string with their
  75. escape sequences and returns the result.
  76. <P>The <A HREF="#item_uri_escape"><CODE>uri_escape()</CODE></A> function takes an optional second argument that
  77. overrides the set of characters that are to be escaped.  The set is
  78. specified as a string that can be used in a regular expression
  79. character class (between [ ]).  E.g.:</P>
  80. <PRE>
  81.   "\x00-\x1f\x7f-\xff"          # all control and hi-bit characters
  82.   "a-z"                         # all lower case characters
  83.   "^A-Za-z"                     # everything not a letter</PRE>
  84. <P>The default set of characters to be escaped is all those which are
  85. <EM>not</EM> part of the <CODE>uric</CODE> character class shown above.</P>
  86. <P></P>
  87. <DT><STRONG><A NAME="item_uri_unescape"><CODE>uri_unescape($string)</CODE></A></STRONG><BR>
  88. <DD>
  89. Returns a string with all %XX sequences replaced with the actual byte
  90. (octet).
  91. <P>This does the same as:</P>
  92. <PRE>
  93.    $string =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;</PRE>
  94. <P>but does not modify the string in-place as this RE would.  Using the
  95. <A HREF="#item_uri_unescape"><CODE>uri_unescape()</CODE></A> function instead of the RE might make the code look
  96. cleaner and is a few characters less to type.</P>
  97. <P>In a simple benchmark test I made I got something like 40% slowdown by
  98. calling the function (instead of the inline RE above) if a few chars
  99. where unescaped and something like 700% slowdown if none where.  If
  100. you are going to unescape a lot of times it might be a good idea to
  101. inline the RE.</P>
  102. <P></P></DL>
  103. <P>The module can also export the <CODE>%escapes</CODE> hash which contains the
  104. mapping from all 256 bytes to the corresponding escape code.  Lookup
  105. in this hash is faster than evaluating <A HREF="../../../lib/Pod/perlfunc.html#item_sprintf"><CODE>sprintf("%%%02X", ord($byte))</CODE></A>
  106. each time.</P>
  107. <P>
  108. <HR>
  109. <H1><A NAME="see also">SEE ALSO</A></H1>
  110. <P><A HREF="../../../site/lib/URI.html">the URI manpage</A></P>
  111. <P>
  112. <HR>
  113. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  114. <P>Copyright 1995-1998 Gisle Aas.</P>
  115. <P>This program is free software; you can redistribute it and/or modify
  116. it under the same terms as Perl itself.</P>
  117. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  118. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  119. <STRONG><P CLASS=block> URI::Escape - Escape and unescape unsafe characters</P></STRONG>
  120. </TD></TR>
  121. </TABLE>
  122.  
  123. </BODY>
  124.  
  125. </HTML>
  126.