Net::IDN::Encode - Internationalizing Domain Names in Applications

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.

You should be familiar with Unicode support in perl, as this module expects correctly encoded input. See perlunitut, the perluniintro manpage and the perlunicode manpage 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):
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):
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):
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):
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+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 follwing characters are recognized as at signs: U+0040 (commercial at), U+FE6B (small commercial at) and U+FF20 (fullwidth commercial at).

AUTHOR

Claus Färber <CFAERBER@cpan.org>

LICENSE

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