Provided by: libnet-idn-encode-perl_2.500-1_amd64 bug

NAME

       Net::IDN::Encode - Internationalizing Domain Names in Applications (IDNA)

SYNOPSIS

         use Net::IDN::Encode ':all';
         my $a = domain_to_ascii("mueller.example.org");
         my $e = email_to_ascii("POSTMASTER@XXXXX");
         my $u = domain_to_unicode('EXAMPLE.XN--11B5BS3A9AJ6G');

DESCRIPTION

       This module provides an easy-to-use interface for encoding and decoding Internationalized
       Domain Names (IDNs).

       IDNs use characters drawn from a large repertoire (Unicode), but IDNA allows the non-ASCII
       characters to be represented using only the ASCII characters already allowed in so-called
       host names today (letter-digit-hyphen, "/[A-Z0-9-]/i").

       Use this module if you just want to convert domain names (or email addresses), using
       whatever IDNA standard is the best choice at the moment.

       You should be familiar with Unicode support in perl, as this module expects correctly
       encoded input. See perlunitut, perluniintro and perlunicode for details.

UNICODE VERSION

       To convert labels correctly between Unicode and ASCII, each character in the label must be
       present in the Unicode version supported by your perl.  Consequently, this module will
       refuse to convert labels with new Unicode characters on older perl versions (see below).

FUNCTIONS

       By default, this module does not export any subroutines. You may use the ":all" tag to
       import everything. You can also use regular expressions such as "/^to_/" or "/^email_/" to
       select some of the functions, see Exporter for details.

       The following functions are available:

       to_ascii( $label, %param )
           Converts a single label $label to ASCII. Will throw an exception on invalid input. If
           $label is already a valid ASCII domain label (including most NON-LDH labels such as
           those used for SRV records and fake A-labels), this function will never fail but
           return $label as-is if conversion would fail.

           This function takes the following optional parameters (%param):

           AllowUnassigned
               (boolean) If set to a true value, code points that are unassigned in the Unicode
               version supported by your perl are allowed. This is an extension over UTS #46.

               While this increases the number of labels that can be converted successfully
               (especially on older perls) and may thus maximizes the compatibility with domain
               names created under future versions of Unicode, it also introduces the risk of
               incorrect conversions.  Characters added in later versions of Unicode might have
               properties that affect the conversion; if these properties are not known on your
               version of perl, you might therefore end up with an incorrect conversion.

               The default is false.

           UseSTD3ASCIIRules
               (boolean) If set to a true value, checks the label for compliance with STD 3
               (RFC 1123) syntax for host name parts. The exact checks done depend on the IDNA
               standard used. Usually, you will want to set this to true.

               Please note that UseSTD3ASCIIRules only affects the conversion between ASCII
               labels (A-labels) and Unicode labels (U-labels). Labels that are in ASCII may
               still be passed-through as-is.

               For historical reasons, the default is false (unlike "domain_to_ascii").

           TransitionalProcessing
               (boolean) If set to true, the conversion will be compatible with IDNA2003. This
               only affects four characters: 'ss' (U+00DF), 'X' (U+03C2), ZWJ (U+200D) and ZWNJ
               (U+200C). Usually, you will want to set this to false.

               The default is false.

           This function does not handle strings that consist of multiple labels (such as domain
           names). Use "domain_to_ascii" instead.

       to_unicode( $label, %param )
           Converts a single label $label to Unicode. Will throw an exception on invalid input.
           If $label is an ASCII label (including most NON-LDH labels such as those used for SRV
           records), this function will not fail but return $label as-is if conversion would
           fail.

           This function takes the same optional parameters as "to_ascii", with the same
           defaults.

           If $label is already in ASCII, this function will never fail but return $label as is
           as a last resort (i.e. pass-through).

           This function takes the following optional parameters (%param):

           AllowUnassigned
           UseSTD3ASCIIRules
               See "to_unicode" above. Please note that there is no need for
               "TransitionalProcessing" for "to_unicode".

           This function does not handle strings that consist of multiple labels (such as domain
           names). Use "domain_to_unicode" instead.

       domain_to_ascii( $label, %param )
           Converts all labels of the hostname $domain (with labels separated by dots) to ASCII
           (using "to_ascii"). Will throw an exception on invalid input.

           This function takes the following optional parameters (%param):

           AllowUnassigned
           TransitionalProcessing
               See "to_unicode" above.

           UseSTD3ASCIIRules
               (boolean) If set to a true value, checks the label for compliance with STD 3
               (RFC 1123) syntax for host name parts.

               The default is true (unlike "to_ascii").

           This function will convert all dots to ASCII, i.e. to U+002E (full stop). The
           following characters are recognized as dots: U+002E (full stop), U+3002 (ideographic
           full stop), U+FF0E (fullwidth full stop), U+FF61 (halfwidth ideographic full stop).

       domain_to_unicode( $domain, %param )
           Converts all labels of the hostname $domain (with labels separated by dots) to
           Unicode. Will throw an exception on invalid input.

           This function takes the same optional parameters as "domain_to_ascii", with the same
           defaults.

           This function takes the following optional parameters (%param):

           AllowUnassigned
           UseSTD3ASCIIRules
               See "domain_to_unicode" above. Please note that there is no
               "TransitionalProcessing" for "domain_to_unicode".

           This function will preserve the original version of dots.  The following characters
           are recognized as dots: U+002E (full stop), U+3002 (ideographic full stop), U+FF0E
           (fullwidth full stop), U+FF61 (halfwidth ideographic full stop).

       email_to_ascii( $email, %param )
           Converts the domain part (right hand side, separated by an at sign) of an
           RFC 2821/2822 email address to ASCII, using "domain_to_ascii". May throw an exception
           on invalid input.

           It takes the same parameters as "domain_to_ascii".

           This function currently does not handle internationalization of the local-part (left
           hand side). Future versions of this module might implement an ASCII conversion for the
           local-part, should one be standardized.

           This function will convert the at sign to ASCII, i.e. to U+0040 (commercial at), as
           well as label separators.  The following characters are recognized as at signs: U+0040
           (commercial at), U+FE6B (small commercial at) and U+FF20 (fullwidth commercial at).

       email_to_unicode( $email, %param )
           Converts the domain part (right hand side, separated by an at sign) of an
           RFC 2821/2822 email address to Unicode, using "domain_to_unicode". May throw an
           exception on invalid input.

           It takes the same parameters as "domain_to_unicode".

           This function currently does not handle internationalization of the local-part (left
           hand side).  Future versions of this module might implement a conversion from ASCII
           for the local-part, should one be standardized.

           This function will preserve the original version of at signs (and label separators).
           The following characters are recognized as at signs: U+0040 (commercial at), U+FE6B
           (small commercial at) and U+FF20 (fullwidth commercial at).

AUTHOR

       Claus Faerber <CFAERBER@cpan.org>

LICENSE

       Copyright 2007-2014 Claus Faerber.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       Net::IDN::Punycode, Net::IDN::UTS46, Net::IDN::IDNA2003, Net::IDN::IDNA2008, UTS #46
       (<http://www.unicode.org/reports/tr46/>), RFC 5890 (<http://tools.ietf.org/html/rfc5890>).