NAME

       Net::LibIDN2 - Perl bindings for GNU Libidn2

SYNOPSIS

         use Net::LibIDN2 ':all';
         use Encode;

         idn2_lookup_u8(Encode::encode_utf8("m\N{U+00FC}\N{U+00DF}li.de"))
           eq 'xn--mli-5ka8l.de';

         idn2_register_u8(
           Encode::encode_utf8("m\N{U+00FC}\N{U+00DF}li"),
           "xn--mli-5ka8l"
         ) eq 'xn--mli-5ka8l';

         Encode::decode_utf8(idn2_to_unicode_88("xn--mli-5ka8l.de"))
           eq "m\N{U+00FC}\N{U+00DF}li.de"

DESCRIPTION

       Provides bindings for GNU Libidn2, a C library for handling internationalized domain names
       based on IDNA 2008, Punycode and TR46.

   Functions
       Net::LibIDN2::idn2_lookup_u8($src, [$flags, [$rc]]);
           Alternative name idn2_to_ascii_8.

           Perform IDNA2008 lookup string conversion on domain name $src, as described in section
           5 of RFC 5891. Note that the input string must be encoded in UTF-8 and be in Unicode
           NFC form.

           Pass IDN2_NFC_INPUT in $flags to convert input to NFC form before further processing.
           IDN2_TRANSITIONAL and IDN2_NONTRANSITIONAL do already imply IDN2_NFC_INPUT.

           Pass IDN2_ALABEL_ROUNDTRIP in flags to convert any input A-labels to U-labels and
           perform additional testing. This is default if used with a libidn2 version >= 2.2. To
           switch this behavior off, pass IDN2_NO_ALABEL_ROUNDTRIP.

           Pass IDN2_TRANSITIONAL to enable Unicode TR46 transitional processing, and
           IDN2_NONTRANSITIONAL to enable Unicode TR46 non-transitional processing.

           Multiple flags may be specified by binary or:ing them together, for example
           IDN2_NFC_INPUT | IDN2_ALABEL_ROUNDTRIP.

           If linked to library GNU Libidn2 version > 2.0.3: IDN2_USE_STD3_ASCII_RULES disabled
           by default.  Previously we were eliminating non-STD3 characters from domain strings
           such as _443._tcp.example.com, or IPs 1.2.3.4/24 provided to libidn2 functions.  That
           was an unexpected regression for applications switching from libidn2 and thus it is no
           longer applied by default. Use IDN2_USE_STD3_ASCII_RULES to enable that behavior
           again.

           On error, returns undef. If a scalar variable is provided in $rc, returns the internal
           libidn2 C library result code as well.

       Net::LibIDN2::idn2_lookup_ul($src, [$flags, [$rc]]);
           Alternative name idn2_to_ascii_l.

           Similar to function "idn2_lookup_u8" but $src is assumed to be encoded in the locale's
           default coding system, and will be transcoded to UTF-8 and NFC normalized before
           returning the result.

       Net::LibIDN2::idn2_register_u8($ulabel, [$alabel, [$flags, [$rc]]]);
           Perform IDNA2008 register string conversion on domain label $ulabel and $alabel, as
           described in section 4 of RFC 5891. Note that the input ulabel must be encoded in
           UTF-8 and be in Unicode NFC form.

           Pass IDN2_NFC_INPUT in $flags to convert input $ulabel to NFC form before further
           processing.

           It is recommended to supply both $ulabel and $alabel for better error checking, but
           supplying just one of them will work. Passing in only $alabel is better than only
           $ulabel. See RFC 5891 section 4 for more information.

           On error, returns undef. If a scalar variable is provided in $rc, returns the internal
           libidn2 C library result code as well.

       Net::LibIDN2::idn2_register_ul($ulabel, [$alabel, [$flags, [$rc]]]);
           Similar to function "idn2_register_u8" but $ulabel is assumed to be encoded in the
           locale's default coding system, and will be transcoded to UTF-8 and NFC normalized
           before returning the result.

       Net::LibIDN2::idn2_to_unicode_88($input, [$flags, [$rc]]);
           Converts a possibly ACE encoded domain name in UTF-8 format into a an UTF-8 encoded
           string (punycode decoding).

           On error, returns undef. If a scalar variable is provided in $rc, returns the internal
           libidn2 C library result code as well.

       Net::LibIDN2::idn2_to_unicode_8l($input, [$flags, [$rc]]);
           Similar to function "idn2_to_unicode_88" but the return value is encoded in the
           locale's default coding system.

       Net::LibIDN2::idn2_to_unicode_ll($input, [$flags, [$rc]]);
           Similar to function "idn2_to_unicode_8l" but $input is also assumed to be encoded in
           the locale's default coding system.

       Net::LibIDN2::idn2_strerror($rc);
           Convert internal libidn2 error code $rc to a human-readable string.

       Net::LibIDN2::idn2_strerror_name($rc);
           Convert internal libidn2 error code $rc to a string corresponding to internal header
           file symbols names like IDN2_MALLOC.

       Net::LibIDN2::idn2_check_version([$req_version])
           Checks that the version of the underlying IDN2 C library is at minimum the one given
           as a string in $req_version and if that is the case returns the actual version string
           of the underlying C library or undef if the condition is not met. If no parameter is
           passed to this function no check is done and only the version  string is returned.

           See IDN2_VERSION for a suitable $req_version string, it corresponds to  the idn2.h C
           header file version at compile time of this Perl module.  Normally these two version
           numbers match, but if you compiled this Perl module against an older libidn2  and then
           run it with a newer libidn2 shared library, they will be different.

   Constants
       IDN2_VERSION
           Pre-processor symbol with a string that describes the C header file version number at
           compile time of this Perl module. Used together with idn2_check_version() to verify
           header file and run-time library consistency.

       IDN2_VERSION_NUMBER
           Pre-processor symbol with a hexadecimal value describing the C header file version
           number at compile time of this Perl module. For example, when the header version is
           1.2.4711 this symbol will have the value 0x01021267. The last four digits are used to
           enumerate development snapshots, but for all public releases they will be 0000.

       IDN2_VERSION_MAJOR
           Pre-processor symbol for the major version number (decimal).  The version scheme is
           major.minor.patchlevel.

       IDN2_VERSION_MINOR
           Pre-processor symbol for the minor version number (decimal).  The version scheme is
           major.minor.patchlevel.

       IDN2_VERSION_PATCH
           Pre-processor symbol for the patch level number (decimal).  The version scheme is
           major.minor.patchlevel.

       IDN2_LABEL_MAX_LENGTH
           Constant specifying the maximum length of a DNS label to 63 characters, as specified
           in RFC 1034.

       IDN2_DOMAIN_MAX_LENGTH
           Constant specifying the maximum size of the wire encoding of a DNS domain to 255
           characters, as specified in RFC 1034. Note that the usual printed representation of a
           domain name is limited to 253 characters if it does not end with a period or 254
           characters if it ends with a period.

   Result codes
       "Net::LibIDN2::IDN2_OK" Successful return.
       "Net::LibIDN2::IDN2_MALLOC" Memory allocation error.
       "Net::LibIDN2::IDN2_NO_CODESET" Could not determine locale string encoding format.
       "Net::LibIDN2::IDN2_ICONV_FAIL" Could not transcode locale string to UTF-8.
       "Net::LibIDN2::IDN2_ENCODING_ERROR" Unicode data encoding error.
       "Net::LibIDN2::IDN2_NFC" Error normalizing string.
       "Net::LibIDN2::IDN2_PUNYCODE_BAD_INPUT" Punycode invalid input.
       "Net::LibIDN2::IDN2_PUNYCODE_BIG_OUTPUT" Punycode output buffer too small.
       "Net::LibIDN2::IDN2_PUNYCODE_OVERFLOW" Punycode conversion would overflow.
       "Net::LibIDN2::IDN2_TOO_BIG_DOMAIN" Domain name longer than 255 characters.
       "Net::LibIDN2::IDN2_TOO_BIG_LABEL" Domain label longer than 63 characters.
       "Net::LibIDN2::IDN2_INVALID_ALABEL" Input A-label is not valid.
       "Net::LibIDN2::IDN2_UALABEL_MISMATCH" Input A-label and U-label does not match.
       "Net::LibIDN2::IDN2_NOT_NFC" String is not NFC.
       "Net::LibIDN2::IDN2_2HYPHEN" String has forbidden two hyphens.
       "Net::LibIDN2::IDN2_HYPHEN_STARTEND" String has forbidden starting/ending hyphen.
       "Net::LibIDN2::IDN2_LEADING_COMBINING" String has forbidden leading combining character.
       "Net::LibIDN2::IDN2_DISALLOWED" String has disallowed character.
       "Net::LibIDN2::IDN2_CONTEXTJ" String has forbidden context-j character.
       "Net::LibIDN2::IDN2_CONTEXTJ_NO_RULE" String has context-j character with no rule.
       "Net::LibIDN2::IDN2_CONTEXTO" String has forbidden context-o character.
       "Net::LibIDN2::IDN2_CONTEXTO_NO_RULE" String has context-o character with no rule.
       "Net::LibIDN2::IDN2_UNASSIGNED" String has forbidden unassigned character.
       "Net::LibIDN2::IDN2_BIDI" String has forbidden bi-directional properties.
       "Net::LibIDN2::IDN2_DOT_IN_LABEL" Label has forbidden dot (TR46).
       "Net::LibIDN2::IDN2_INVALID_TRANSITIONAL" Label has character forbidden in transitional
       mode (TR46).
       "Net::LibIDN2::IDN2_INVALID_NONTRANSITIONAL" Label has character forbidden in non-
       transitional mode (TR46).

AUTHOR

       Thomas Jacob, https://github.com/gnuthor

SEE ALSO

       perl(1), RFC 5890-5893, TR 46, https://gitlab.com/libidn/libidn2.