=head1 NAME URL::PercentEncode - Safe percent-encoding and percent-decoding implementation =head1 IMPORTANT This module is now B<DEPRECATED> in favor of new modules: <https://github.com/manakai/perl-web-url>. =head1 SYNOPSIS use URL::PercentEncode; my $encoded = percent_encode_c $utf8_string; my $encoded = percent_encode_b $byte_string; my $utf8_string = percent_decode_c $encoded; my $byte_string = percent_decode_b $encoded; my $form_data = parse_form_urlencoded_b $encoded; =head1 DESCRIPTION This module, C<URL::PercentEncode>, provides four functions to percent-encode or percent-decode strings in a slightly safe manner. Any string, utf8-flagged or -unflagged, can be encoded or decoded in URL's %HH format (percent-encoding, formally known as URI escape or URL encoding). =head1 FUNCTIONS The module exports the following functions: =over 4 =item $encoded = percent_encode_c $utf8_string Percent-encode a character string (i.e. a utf8-flagged string). =item $encoded = percent_encode_b $byte_string Percent-encode a byte string. =item $utf8_string = percent_decode_c $encoded Decode a percent-encoded utf8 character string. =item $byte_string = percent_decode_b $encoded Decode a percent-encoded byte string. =item $form_data = parse_form_urlencoded_b $encoded Intepret the given string as C<application/x-www-form-urlencoded>-encoded form data set and return the decoded data as a set of byte strings. The input must be a byte string or the C<undef> value. The method return a hash reference, which contains zero or more key-value pairs where a value is an array reference. Any name-value pairs contained in the input string is stored in the hash reference as a key and one of values in the array reference for the key. Order of name-value pairs are not preserved as the return value is a hash reference. However, order of values sharing their names are preserved as order of values in the array reference. Values are percent-decoded but left character-encoded (i.e. left as byte strings). This method is an implementation of the steps to "decode C<application/x-www-form-urlencoded> payloads", except: The I<isindex> flag is not supported. The I<encoding> parameter and the C<_charset_> hack is not supported as the method does not handle character encoding. The C<U+003B> C<SEMICOLON> character (C<;>) is also used as delimiter as well as the C<U+0026> C<AMPERSAND> character (C<&>) for backward compatibility with popular implementations of C<application/x-www-form-urlencoded> decoders (This is a willful violation to the spec). =back =head1 SEE ALSO URL (HTML Standard) <http://www.whatwg.org/specs/web-apps/current-work/complete.html#url>. URI (RFC 3986) <http://tools.ietf.org/html/rfc3986>. IRI (RFC 3987) <http://tools.ietf.org/html/rfc3987>. The steps to "decode C<application/x-www-form-urlencoded> payloads" (HTML Standard) <http://www.whatwg.org/specs/web-apps/current-work/#application/x-www-form-urlencoded-encoding-algorithm>. =head1 DISTRIBUTION Latest version of this Perl modules is available in the Git repository: <https://github.com/wakaba/perl-web-utils> or <https://suika.suikawiki.org/gate/git/wi/perl/webutils.git/>. =head1 CHANGES =over 4 =item 2010-04-11 (1.0) First version. =item 2012-02-25 (2.0) Added C<application/x-www-form-urlencoded> support. =back =head1 AUTHOR Wakaba <wakaba@suikawiki.org>. =head1 LICENSE Copyright 2010-2012 Wakaba <wakaba@suikawiki.org>. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut