.\" -*- 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::Punycode 3pm"
.TH Net::IDN::Punycode 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::Punycode \- A Bootstring encoding of Unicode for IDNA (RFC\ 3492)
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  use Net::IDN::Punycode qw(:all);
\&  $punycode = encode_punycode($unicode);
\&  $unicode  = decode_punycode($punycode);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module implements the Punycode encoding, and only the Punycode encoding.
.PP
This module does not implement any other steps required for converting
internationalized domain names (IDNs) to and from ASCII. In particular, it does
not do any string preparation as specified by \fINameprep\fR/\fIIDNA2008\fR/\fIPRECIS\fR
and does not add nor remove the ACE prefix (\f(CW\*(C`xn\-\-\*(C'\fR). Thus, use
Net::IDN::Encode if you want to convert domain names.
.PP
Punycode is an instance of a more general algorithm called Bootstring, which
allows strings composed from a small set of "basic" code points to uniquely
represent any string of code points drawn from a larger set. Punycode is
Bootstring with particular parameter values appropriate for IDNA.
.SH WARNING
.IX Header "WARNING"
You may be tempted to use this module directly and add/remove the ACE prefix
(\f(CW\*(C`xn\-\-\*(C'\fR) in your code for performance reasons. Usually, this is not a good
idea.  If you convert domain labels (or other strings) without proper
preparation, you may end up with an ASCII encoding that is not interoperable or
even poses security issues due to spoofing.
.PP
Even if you think that your domain names are valid and already mapped to the
correct form, this may not be true. For example, some environments might
automatically convert your perfectly valid domain names to a different but
equivalent Unicode normalization form (e.g., NFD instead of NFC), which already
breaks IDNA.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
No functions are exported by default. You can use the tag \f(CW\*(C`:all\*(C'\fR
or import them individually.
.PP
The following functions are available:
.IP encode_punycode($input) 4
.IX Item "encode_punycode($input)"
Encodes \f(CW$input\fR with Punycode and returns the result.
.Sp
This function will throw an exception on invalid/unencodable input.
.IP decode_punycode($input) 4
.IX Item "decode_punycode($input)"
Decodes \f(CW$input\fR with Punycode and returns the result.
.Sp
This function will throw an exception on invalid input.
.SH AUTHORS
.IX Header "AUTHORS"
Tatsuhiko Miyagawa <miyagawa@bulknews.net> (versions 0.01 to 0.02)
.PP
Claus Färber <CFAERBER@cpan.org> (versions 1.000 and higher)
.SH LICENSE
.IX Header "LICENSE"
Copyright 2002\-2004 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
.PP
Copyright 2007\-2014 Claus Färber <CFAERBER@cpan.org>
.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"
RFC\ 3492 (<http://www.ietf.org/rfc/rfc3492.txt>),
IETF::ACE, Convert::RACE