Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::IDN::Encode(3)   User Contributed Perl Documentation  Net::IDN::Encode(3)

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

perl v5.24.1			  2017-07-02		   Net::IDN::Encode(3)

NAME | SYNOPSIS | DESCRIPTION | UNICODE VERSION | FUNCTIONS | AUTHOR | LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::IDN::Encode&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help