/ 
Net-IDN-Encode-1.999_20111228
River stage two • 13 direct dependents • 37 total dependents
/ Net::IDN::Encode

NAME

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

SYNOPSIS

use Net::IDN::Encode ':all';
my $a = domain_to_ascii("müller.example.org");
my $e = email_to_ascii("POSTMASTER@例。テスト");
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-hypen, /[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.

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 in ASCII, this function will never fail but return $label as is as a last resort.

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

AllowUnassigned

(boolean) If set to a true value, unassigned code points in the label are allowed. While maximizing the compatibility with future versions of Unicode and/or IDNA, this option is also dangerous: Characters added in future versions of Unicode might have properties that affect the conversion; you might therefore end up with a conversion that is incompatible with later standards. Therefore, set this to false unless you know what you are doing.

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.

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: 'ß' (U+00DF), 'ς' (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 in ASCII, this function will never fail but return $label as is as a last resort.

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 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 seperated 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 seperated 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 follwing characters are recognized as at signs: U+0040 (commercial at), 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 follwing characters are recognized as at signs: U+0040 (commercial at), U+FF20 (fullwidth commercial at).

IDNA STANDARDS

This module currently implements UTS #46 (Unicode IDNA Compatibility Processing), which is the specification that will create the least surprising results for most use cases.

UTS #46, however, is only one of several different standards covering the internationalization of domain names. Although all standards are mostly compatible, they do differ in some aspects:

IDNA2003

IDNA2003, which is defined in RFC 3490 (http://tools.ietf.org/html/rfc3490) and related documents, was the original specification for internationalization of domain names.

However, some issues were subsequently identified with IDNA2003: The specification was tied to Unicode 3.2 and therefore did not allow characters added in newer versions of Unicode (without updating the specifications).

Furthermore, a few characters were mapped to other characters or deleted although they would carry meaning in some languages (i.e. 'ß' and 'ς' were mapped to 'ss' and 'σ'; ZWJ and ZWNJ were mapped to nothing, although some scripts require them for correct display).

See also Net::IDN::IDNA2003.

IDNA2008

IDNA2008, which is defined in RFC 5890 (http://tools.ietf.org/html/rfc5890) and related documents, resolves the issues found in IDNA2003.

For most parts, IDNA2008 only allows domain names that would be disallowed and/or mapped to other domain names under IDNA2003. An implementation of IDNA2003 would not be able to access these domain names, of course.

However, IDNA2008 also disallows a number of characters had been allowed in IDNA2003 (mostly symbols). An implementation of IDNA2008 would therefore no longer be able to access domain names such as √.com, which had been registered under IDNA2003.

See also Net::IDN::IDNA2008.

UTS #46

Unicode Technical Standard #46 (UTS #46) solves this problem by allowing domain names that are valid in either IDNA2003 or IDNA2008, and thus to all domains registered under either IDNA2003 or IDNA2008.

UTS #46 also allows some domain names that are valid in neither IDNA2003 nor IDNA2008, relying on DNS lookup failing for such domain names. This makes UTS #46 the perfect fit for domain lookup (be liberal in what you accept) but unsuitable for validating domain names prior to registration (be conservative in what you send).

See also Net::IDN::UTS46.

For more information, see the specifications indicated above.

AUTHOR

Claus Färber <CFAERBER@cpan.org>

LICENSE

Copyright 2007-2011 Claus Färber.

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).