Skip to content

wakaba/perl-web-utils

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

=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

Releases

No releases published

Packages

No packages published