NAME


URI::Encode - Simple percent Encoding/Decoding

    <a href="https://travis-ci.org/mithun/perl-uri-encode"><img src="https://travis-ci.org/mithun/perl-uri-encode.svg?branch=master"></a>



SYNOPSIS


    # OOP Interface
    use URI::Encode;
    my $uri     = URI::Encode->new( { encode_reserved => 0 } );
    my $encoded = $uri->encode($data);
    my $decoded = $uri->decode($encoded);

    # Functional
    use URI::Encode qw(uri_encode uri_decode);
    my $encoded = uri_encode($data);
    my $decoded = uri_decode($encoded);



DESCRIPTION


This modules provides simple URI (Percent) encoding/decoding

The main purpose of this module (at least for me) was to provide an easy
method to encode strings (mainly URLs) into a format which can be pasted
into a plain text emails, and that those links are 'click-able' by the
person reading that email. This can be accomplished by NOT encoding the
reserved characters.

This module can also be useful when using [HTTP::Tiny][] to ensure the
URLs are properly escaped.

THIS MODULE DOES NOT ENCODE RESERVED CHARACTERS BY DEFAULT. If you are
looking for speed and want to encode reserved characters, use
[URI::Escape::XS][]

See [this script][] for a comparison on encoding results and
performance.



METHODS


new()

Creates a new object, no arguments are required

    my $encoder = URI::Encode->new(\%options);

The following options can be passed to the constructor

-   encode_reserved

        my $encoder = URI::Encode->new({encode_reserved => 0});

    If true, ["Reserved Characters"][] are also encoded. Defaults
    to false.

-   double_encode

        my $encoder = URI::Encode->new({double_encode => 1});

    If false, characters that are already percent-encoded will not be
    encoded again. Defaults to true.

        my $encoder = URI::Encode->new({double_encode => 0});
        print $encoder->encode('http://perl.com/foo%20bar'); # prints http://perl.com/foo%20bar


encode($url, \%options)

This method encodes the URL provided. The $url provided is first
converted into UTF-8 before percent encoding. Options set in the
constructor, or defaults, can be overridden by passing them as the
(optional) second argument. Options passed must be a hashref.

    $uri->encode("http://perl.com/foo bar");
    $uri->encode( "http://perl.com/foo bar", { encode_reserved => 1 } );


decode($url)

This method decodes a 'percent' encoded URL. If you had encoded the URL
using this module (or any other method), chances are that the URL was
converted to UTF-8 before 'percent' encoding. Be sure to check the
format and convert back if required.

    $uri->decode("http%3A%2F%2Fperl.com%2Ffoo%20bar");



EXPORTED FUNCTIONS


The following functions are exported upon request. This provides a
non-OOP interface

-   uri_encode($url, \%options)
-   uri_decode($url)



CHARACTER CLASSES


Reserved Characters

The following characters are considered as reserved ([RFC 3986][]). They
will be encoded only if requested.

     ! * ' ( ) ; : @ & = + $ , / ? # [ ]


Unreserved Characters

The following characters are considered as Unreserved. They will not be
encoded

    a-z
    A-Z
    0-9
    - _ . ~



DEPENDENCIES


[Encode][]



ACKNOWLEDGEMENTS


Gisle Aas for [URI::Escape][]

David Nicol for [Tie::UrlEncoder][]



SEE ALSO


[RFC 3986][RFC 3986]

[URI::Escape][]

[URI::Escape::XS][]

[URI::Escape::JavaScript][]

[Tie::UrlEncoder][]



BUGS AND LIMITATIONS


Please report any bugs or feature requests at
https://github.com/mithun/perl-uri-encode/issues



AUTHOR


Mithun Ayachit mithun@cpan.org



LICENSE AND COPYRIGHT


Copyright (c) 2014, Mithun Ayachit. All rights reserved.

This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See [perlartistic][].

  [HTTP::Tiny]: https://metacpan.org/pod/HTTP::Tiny
  [URI::Escape::XS]: https://metacpan.org/pod/URI::Escape::XS
  [this script]: https://github.com/mithun/perl-uri-encode/raw/master/.author/benchmark.pl
  ["Reserved Characters"]: #reserved-characters
  [RFC 3986]: http://tools.ietf.org/html/rfc3986
  [Encode]: https://metacpan.org/pod/Encode
  [URI::Escape]: https://metacpan.org/pod/URI::Escape
  [Tie::UrlEncoder]: https://metacpan.org/pod/Tie::UrlEncoder
  [URI::Escape::JavaScript]: https://metacpan.org/pod/URI::Escape::JavaScript
  [perlartistic]: https://metacpan.org/pod/perlartistic