.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "Net::IDN::UTS46 3pm"
.TH Net::IDN::UTS46 3pm 2024-03-10 "perl v5.38.2" "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::UTS46 \- Unicode IDNA Compatibility Processing (UTS\ #46)
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  use Net::IDN:: \*(Aq:all\*(Aq;
\&  my $a = uts46_to_ascii("müller.example.org");
\&  my $b = Net::IDN::UTS46::to_unicode(\*(AqEXAMPLE.XN\-\-11B5BS3A9AJ6G\*(Aq);
\&  
\&  $domain =~ m/\eP{Net::IDN::UTS46::IsDisallowed} and die \*(Aqoops\*(Aq;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module implements the Unicode Technical Standard #46 (Unicode IDNA
Compatibility Processing). UTS\ #46 is one variant of Internationalized Domain
Names (IDN), which aims to be compatible with domain names registered under
either IDNA2003 or IDNA2008.
.PP
You should use this module if you want an exact implementation of the UTS\ #46
specification.
.PP
However, if you just want to convert domain names and don't care which standard
is used internally, you should use Net::IDN::Encode instead.
.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.
.PP
You can omit the \f(CW\*(Aquts46_\*(Aq\fR prefix when accessing the functions with a
full-qualified module name (e.g. you can access \f(CW\*(C`uts46_to_unicode\*(C'\fR as
\&\f(CW\*(C`Net::IDN::UTS46::uts46_to_unicode\*(C'\fR or \f(CW\*(C`Net::IDN::UTS46::to_unicode\*(C'\fR.
.PP
The following functions are available:
.ie n .IP "uts46_to_ascii( $domain, %param )" 4
.el .IP "uts46_to_ascii( \f(CW$domain\fR, \f(CW%param\fR )" 4
.IX Item "uts46_to_ascii( $domain, %param )"
Implements the "ToASCII" function from UTS\ #46, section\ 4.2. It converts a domain name to
ASCII and throws 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"
(boolean) If set to a true value, unassigned code points in the label are
allowed. This is an extension over UTS\ #46.
.Sp
The default is false.
.IP UseSTD3ASCIIRules 4
.IX Item "UseSTD3ASCIIRules"
(boolean) If set to a true value, checks the label for compliance with STD\ 3
(RFC\ 1123) syntax for host name parts.
.Sp
The default is true.
.IP TransitionalProcessing 4
.IX Item "TransitionalProcessing"
(boolean) If set to true, the conversion will be compatible with IDNA2003. This
only affects four characters: \f(CW\*(Aqß\*(Aq\fR (U+00DF), 'ς' (U+03C2), ZWJ (U+200D) and
ZWNJ (U+200C). Usually, you will want to set this to false.
.Sp
The default is false.
.RE
.RS 4
.RE
.ie n .IP "uts46_to_unicode( $label, %param )" 4
.el .IP "uts46_to_unicode( \f(CW$label\fR, \f(CW%param\fR )" 4
.IX Item "uts46_to_unicode( $label, %param )"
Implements the "ToUnicode" function from UTS\ #46, section\ 4.3. It converts a domain name to
Unicode and throws 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"
.Vb 1
\&  see above.
.Ve
.IP UseSTD3ASCIIRules 4
.IX Item "UseSTD3ASCIIRules"
.Vb 1
\&  see above.
.Ve
.IP TransitionalProcessing 4
.IX Item "TransitionalProcessing"
(boolean) If given, this parameter must be false. The UTS\ #46 specification
does not define transitional processing for ToUnicode.
.RE
.RS 4
.RE
.SH "UNICODE CHARACTER PROPERTIES"
.IX Header "UNICODE CHARACTER PROPERTIES"
This module also defines the character properties listed below.
.PP
Each character has exactly one of the following properties:
.ie n .IP """\ep{Net::IDN::UTS46::IsValid}""" 4
.el .IP \f(CW\ep{Net::IDN::UTS46::IsValid}\fR 4
.IX Item "p{Net::IDN::UTS46::IsValid}"
The code point is valid, and not modified (i.e. a deviation character) in UTS\ #46.
.ie n .IP """\ep{Net::IDN::UTS46::IsIgnored}""" 4
.el .IP \f(CW\ep{Net::IDN::UTS46::IsIgnored}\fR 4
.IX Item "p{Net::IDN::UTS46::IsIgnored}"
The code point is removed (i.e. mapped to an empty string) in UTS\ #46.
.ie n .IP """\ep{Net::IDN::UTS46::IsMapped}""" 4
.el .IP \f(CW\ep{Net::IDN::UTS46::IsMapped}\fR 4
.IX Item "p{Net::IDN::UTS46::IsMapped}"
The code point is replaced by another string in UTS\ #46.
.ie n .IP """\ep{Net::IDN::UTS46::IsDeviation}""" 4
.el .IP \f(CW\ep{Net::IDN::UTS46::IsDeviation}\fR 4
.IX Item "p{Net::IDN::UTS46::IsDeviation}"
The code point is either mapped or valid, depending on whether the processing is transitional or not.
.ie n .IP """\ep{Net::IDN::UTS46::IsDisallowed}""" 4
.el .IP \f(CW\ep{Net::IDN::UTS46::IsDisallowed}\fR 4
.IX Item "p{Net::IDN::UTS46::IsDisallowed}"
The code point is not allowed in UTS\ #46.
.ie n .IP """\ep{Net::IDN::UTS46::IsDisallowedSTD3Ignored}""" 4
.el .IP \f(CW\ep{Net::IDN::UTS46::IsDisallowedSTD3Ignored}\fR 4
.IX Item "p{Net::IDN::UTS46::IsDisallowedSTD3Ignored}"
The code point is not allowed in UTS\ #46 if \f(CW\*(C`UseSTDASCIIRules\*(C'\fR are used but would be ignored otherwise.
.ie n .IP """\ep{Net::IDN::UTS46::IsDisallowedSTD3Mapped}""" 4
.el .IP \f(CW\ep{Net::IDN::UTS46::IsDisallowedSTD3Mapped}\fR 4
.IX Item "p{Net::IDN::UTS46::IsDisallowedSTD3Mapped}"
The code point is not allowed in UTS\ #46 if \f(CW\*(C`UseSTDASCIIRules\*(C'\fR are used but would be mapped otherwise.
.SH AUTHOR
.IX Header "AUTHOR"
Claus Färber <CFAERBER@cpan.org>
.SH LICENSE
.IX Header "LICENSE"
Copyright 2011\-2018 Claus Fä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::UTS46::Mapping, Net::IDN::Encode, UTS\ #46 (<http://www.unicode.org/reports/tr46/>)