.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::IDN::Encode 3"
.TH Net::IDN::Encode 3 "2016-08-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::IDN::Encode \- Internationalizing Domain Names in Applications (IDNA)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  use Net::IDN::Encode \*(Aq:all\*(Aq;
\&  my $a = domain_to_ascii("mu\*:ller.example.org");
\&  my $e = email_to_ascii("POSTMASTER@XXXXX");
\&  my $u = domain_to_unicode(\*(AqEXAMPLE.XN\-\-11B5BS3A9AJ6G\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an easy-to-use interface for encoding and
decoding Internationalized Domain Names (IDNs).
.PP
IDNs use characters drawn from a large repertoire (Unicode), but
\&\s-1IDNA\s0 allows the non-ASCII characters to be represented using only
the \s-1ASCII\s0 characters already allowed in so-called host names today
(letter-digit-hypen, \f(CW\*(C`/[A\-Z0\-9\-]/i\*(C'\fR).
.PP
Use this module if you just want to convert domain names (or email addresses),
using whatever \s-1IDNA\s0 standard is the best choice at the moment.
.PP
You should be familiar with Unicode support in perl, as this module expects
correctly encoded input. See perlunitut, perluniintro and perlunicode
for details.
.SH "UNICODE VERSION"
.IX Header "UNICODE VERSION"
To convert labels correctly between Unicode and \s-1ASCII,\s0 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).
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
By default, this module does not export any subroutines. You may
use the \f(CW\*(C`:all\*(C'\fR tag to import everything. You can also use regular
expressions such as \f(CW\*(C`/^to_/\*(C'\fR or \f(CW\*(C`/^email_/\*(C'\fR to select some of
the functions, see Exporter for details.
.PP
The following functions are available:
.ie n .IP "to_ascii( $label, %param )" 4
.el .IP "to_ascii( \f(CW$label\fR, \f(CW%param\fR )" 4
.IX Item "to_ascii( $label, %param )"
Converts a single label \f(CW$label\fR to \s-1ASCII.\s0 Will throw an exception on invalid
input. If \f(CW$label\fR is already a valid \s-1ASCII\s0 domain label (including most
NON-LDH labels such as those used for \s-1SRV\s0 records and fake A\-labels), this
function will never fail but return \f(CW$label\fR as-is if conversion would fail.
.Sp
This function takes the following optional parameters (\f(CW%param\fR):
.RS 4
.IP "AllowUnassigned" 4
.IX Item "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
\&\s-1UTS\s0\ #46.
.Sp
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.
.Sp
The default is false.
.IP "UseSTD3ASCIIRules" 4
.IX Item "UseSTD3ASCIIRules"
(boolean) If set to a true value, checks the label for compliance with \s-1STD\s0\ 3
(\s-1RFC\s0\ 1123) syntax for host name parts. The exact checks done depend on the
\&\s-1IDNA\s0 standard used. Usually, you will want to set this to true.
.Sp
Please note that UseSTD3ASCIIRules only affects the conversion between \s-1ASCII\s0
labels (A\-labels) and Unicode labels (U\-labels). Labels that are in \s-1ASCII\s0 may
still be passed-through as-is.
.Sp
For historical reasons, the default is false (unlike \f(CW\*(C`domain_to_ascii\*(C'\fR).
.IP "TransitionalProcessing" 4
.IX Item "TransitionalProcessing"
(boolean) If set to true, the conversion will be compatible with \s-1IDNA2003.\s0 This
only affects four characters: \f(CW\*(Aq\*8\*(Aq\fR (U+00DF), 'X' (U+03C2), \s-1ZWJ \s0(U+200D) and
\&\s-1ZWNJ \s0(U+200C). Usually, you will want to set this to false.
.Sp
The default is false.
.RE
.RS 4
.Sp
This function does not handle strings that consist of multiple labels (such as
domain names). Use \f(CW\*(C`domain_to_ascii\*(C'\fR instead.
.RE
.ie n .IP "to_unicode( $label, %param )" 4
.el .IP "to_unicode( \f(CW$label\fR, \f(CW%param\fR )" 4
.IX Item "to_unicode( $label, %param )"
Converts a single label \f(CW$label\fR to Unicode. Will throw an exception on
invalid input. If \f(CW$label\fR is an \s-1ASCII\s0 label (including most NON-LDH labels
such as those used for \s-1SRV\s0 records), this function will not fail but return
\&\f(CW$label\fR as-is if conversion would fail.
.Sp
This function takes the same optional parameters as \f(CW\*(C`to_ascii\*(C'\fR,
with the same defaults.
.Sp
If \f(CW$label\fR is already in \s-1ASCII,\s0 this function will never fail but return
\&\f(CW$label\fR as is as a last resort (i.e. pass-through).
.Sp
This function takes the following optional parameters (\f(CW%param\fR):
.RS 4
.IP "AllowUnassigned" 4
.IX Item "AllowUnassigned"
.PD 0
.IP "UseSTD3ASCIIRules" 4
.IX Item "UseSTD3ASCIIRules"
.PD
See \f(CW\*(C`to_unicode\*(C'\fR above. Please note that there is no need for
\&\f(CW\*(C`TransitionalProcessing\*(C'\fR for \f(CW\*(C`to_unicode\*(C'\fR.
.RE
.RS 4
.Sp
This function does not handle strings that consist of multiple labels (such as
domain names). Use \f(CW\*(C`domain_to_unicode\*(C'\fR instead.
.RE
.ie n .IP "domain_to_ascii( $label, %param )" 4
.el .IP "domain_to_ascii( \f(CW$label\fR, \f(CW%param\fR )" 4
.IX Item "domain_to_ascii( $label, %param )"
Converts all labels of the hostname \f(CW$domain\fR (with labels separated by dots)
to \s-1ASCII \s0(using \f(CW\*(C`to_ascii\*(C'\fR). Will throw an exception on invalid input.
.Sp
This function takes the following optional parameters (\f(CW%param\fR):
.RS 4
.IP "AllowUnassigned" 4
.IX Item "AllowUnassigned"
.PD 0
.IP "TransitionalProcessing" 4
.IX Item "TransitionalProcessing"
.PD
See \f(CW\*(C`to_unicode\*(C'\fR above.
.IP "UseSTD3ASCIIRules" 4
.IX Item "UseSTD3ASCIIRules"
(boolean) If set to a true value, checks the label for compliance with \s-1STD\s0\ 3
(\s-1RFC\s0\ 1123) syntax for host name parts.
.Sp
The default is true (unlike \f(CW\*(C`to_ascii\*(C'\fR).
.RE
.RS 4
.Sp
This function will convert all dots to \s-1ASCII,\s0 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).
.RE
.ie n .IP "domain_to_unicode( $domain, %param )" 4
.el .IP "domain_to_unicode( \f(CW$domain\fR, \f(CW%param\fR )" 4
.IX Item "domain_to_unicode( $domain, %param )"
Converts all labels of the hostname \f(CW$domain\fR (with labels separated by dots)
to Unicode. Will throw an exception on invalid input.
.Sp
This function takes the same optional parameters as \f(CW\*(C`domain_to_ascii\*(C'\fR,
with the same defaults.
.Sp
This function takes the following optional parameters (\f(CW%param\fR):
.RS 4
.IP "AllowUnassigned" 4
.IX Item "AllowUnassigned"
.PD 0
.IP "UseSTD3ASCIIRules" 4
.IX Item "UseSTD3ASCIIRules"
.PD
See \f(CW\*(C`domain_to_unicode\*(C'\fR above. Please note that there is no \f(CW\*(C`TransitionalProcessing\*(C'\fR
for \f(CW\*(C`domain_to_unicode\*(C'\fR.
.RE
.RS 4
.Sp
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).
.RE
.ie n .IP "email_to_ascii( $email, %param )" 4
.el .IP "email_to_ascii( \f(CW$email\fR, \f(CW%param\fR )" 4
.IX Item "email_to_ascii( $email, %param )"
Converts the domain part (right hand side, separated by an at sign) of an \s-1RFC\s0\ 2821/2822 email address to \s-1ASCII,\s0 using \f(CW\*(C`domain_to_ascii\*(C'\fR. May throw an
exception on invalid input.
.Sp
It takes the same parameters as \f(CW\*(C`domain_to_ascii\*(C'\fR.
.Sp
This function currently does not handle internationalization of the local-part
(left hand side). Future versions of this module might implement an \s-1ASCII\s0
conversion for the local-part, should one be standardized.
.Sp
This function will convert the at sign to \s-1ASCII,\s0 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).
.ie n .IP "email_to_unicode( $email, %param )" 4
.el .IP "email_to_unicode( \f(CW$email\fR, \f(CW%param\fR )" 4
.IX Item "email_to_unicode( $email, %param )"
Converts the domain part (right hand side, separated by an at sign) of an \s-1RFC\s0\ 2821/2822 email address to Unicode, using \f(CW\*(C`domain_to_unicode\*(C'\fR. May throw an
exception on invalid input.
.Sp
It takes the same parameters as \f(CW\*(C`domain_to_unicode\*(C'\fR.
.Sp
This function currently does not handle internationalization of the local-part
(left hand side).  Future versions of this module might implement a conversion
from \s-1ASCII\s0 for the local-part, should one be standardized.
.Sp
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).
.SH "AUTHOR"
.IX Header "AUTHOR"
Claus Fa\*:rber <CFAERBER@cpan.org>
.SH "LICENSE"
.IX Header "LICENSE"
Copyright 2007\-2014 Claus Fa\*:rber.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::IDN::Punycode, Net::IDN::UTS46, Net::IDN::IDNA2003,
Net::IDN::IDNA2008, \s-1UTS\s0\ #46 (<http://www.unicode.org/reports/tr46/>),
\&\s-1RFC\s0\ 5890 (<http://tools.ietf.org/html/rfc5890>).