txt: ## dist_zef-raku-community-modules-Net-LibIDN2.md
  [![Actions Status](https://github.com/raku-community-modules/Net-LibIDN2/workflows/test/badge.svg)](https://github.com/raku-community-modules/Net-LibIDN2/actions)
  
  # NAME
  
  Net::LibIDN2 - Raku bindings for GNU LibIDN2
  
  # SYNOPSIS
  
  ```
      use Net::LibIDN2;
  
      my $idn = Net::LibIDN2.new;
  
      my Int $code;
      my $ulabel = "m\xFC\xDFli";
      my $alabel = $idn.lookup_u8($ulabel, IDN2_NFC_INPUT, $code);
      say "$alabel $code"; # xn--mli-5ka8l 0
  
      my $result = $idn.register_u8($ulabel, $alabel, IDN2_NFC_INPUT, $code);
      say "$result $code"; # xn--mli-5ka8l 0
      say $idn.strerror($code);      # success
      say $idn.strerror_name($code); # IDN2_OK
  
  ```
  
  # DESCRIPTION
  
  Net::LibIDN2 is a Raku wrapper for the GNU LibIDN2 library.
  
  Using this module requires a native LibIDN2 dependency. Here's how to install it for your OS:
  
  * Windows
  
  Clone <https://gitlab.com/libidn/libidn2> and follow the install instructions in the README. Don't forget to add the path to the installed LibIDN2 to your PATH environment variable!
  
  * OS X
  
    $ brew install libidn2
  * Ubuntu/Debian
  
    $ sudo apt-get install libidn2
  * OpenSUSE
  
    $ sudo zypper install libidn2
  * Fedora
  
    $ sudo yum install libidn2
  * Arch/Manjaro
  
    $ sudo pacman -S libidn2
  * FreeBSD
  
    # pkg install libidn2
  
  or
  
  ```
  # cd /usr/ports/devel/libidn2
  # make config
  # make
  # make install
  
  ```
  
  * OpenBSD
  
    $ doas pkg\_add libidn2
  
  or
  
  ```
  $ cd /usr/ports/devel/libidn2
  $ doas make
  $ doas make install
  
  ```
  
  * NetBSD
  
    # pkgin install libidn2
  
  or
  
  ```
  # cd /usr/pkgsrc/devel/libidn2
  # make
  # make install
  
  ```
  
  # METHODS
  
  * **Net::LibIDN2.check\_version**(--> Version)
  * **Net::LibIDN2.check\_version**(Str *$version* --> Version)
  * **Net::LibIDN2.check\_version**(Version *$version* --> Version)
  
  Compares `$version` against the version of LibIDN2 installed and returns either an empty string if `$version` is greater than the version installed, or `IDN2_VERSION` otherwise.
  
  * **Net::LibIDN2.strerror**(Int *$errno* --> Str)
  
  Returns the error represented by `$errno` in human readable form.
  
  * **Net::LibIDN2.strerror\_name**(Int *$errno* --> Str)
  
  Returns the internal error name of `$errno`.
  
  * **Net::LibIDN2.to\_ascii\_8z**(Str *$input* --> Str)
  * **Net::LibIDN2.to\_ascii\_8z**(Str *$input*, Int *$flags* --> Str)
  * **Net::LibIDN2.to\_ascii\_8z**(Str *$input*, Int *$flags*, Int *$code* is rw --> Str)
  
  Converts a UTF8 encoded string `$input` to ASCII and returns the output. `$code`, if provided, is assigned to `IDN2_OK` on success, or another error code otherwise. Requires LibIDN2 v2.0.0 or greater.
  
  * **Net::LibIDN2.to\_unicode\_8z8z**(Str *$input* --> Str)
  * **Net::LibIDN2.to\_unicode\_8z8z**(Str *$input*, Int *$flags* --> Str)
  * **Net::LibIDN2.to\_unicode\_8z8z**(Str *$input*, Int *$flags*, Int *$code* is rw --> Str)
  
  Converts an ACE encoded domain name `$input` to UTF8 and returns the output. `$code`, if provided, is assigned to `IDN2_OK` on success, or another error code otherwise. Requires LibIDN v2.0.0 or greater.
  
  * **Net::LibIDN2.lookup\_u8**(Str *$input* --> Str)
  * **Net::LibIDN2.lookup\_u8**(Str *$input*, Int *$flags* --> Str)
  * **Net::LibIDN2.lookup\_u8**(Str *$input*, Int *$flags*, Int *$code* is rw --> Str)
  
  Performs an IDNA2008 lookup string conversion on `$input`. See RFC 5891, section 5. `$input` must be a UTF8 encoded string in NFC form if no `IDN2_NFC_INPUT` flag is passed.
  
  * **Net::LibIDN2.register\_u8**(Str *$uinput*, Str *$ainput* --> Str)
  * **Net::LibIDN2.register\_u8**(Str *$uinput*, Str *$ainput*, Int *$flags* --> Str)
  * **Net::LibIDN2.register\_u8**(Str *$uinput*, Str *$ainput*, Int *$flags*, Int *$code* is rw --> Str)
  
  Performs an IDNA2008 register string conversion on `$uinput` and `$ainput`. See RFC 5891, section 4. `$uinput` must be a UTF8 encoded string in NFC form if no `IDN2_NFC_INPUT` flag is passed. `$ainput` must be an ACE encoded string.
  
  # CONSTANTS
  
  * Int **IDN2\_LABEL\_MAX\_LENGTH**
  
  The maximum label length.
  
  * Int **IDN2\_DOMAIN\_MAX\_LENGTH**
  
  The maximum domain name length.
  
  ## VERSIONING
  
  * Str **IDN2\_VERSION**
  
  The version of LibIDN2 installed.
  
  * Int **IDN2\_VERSION\_NUMBER**
  
  The version of LibIDN2 installed represented as a 32 bit integer. The first pair of bits represents the major version, the second represents the minor version, and the last 4 represent the patch version.
  
  * Int **IDN2\_VERSION\_MAJOR**
  
  The major version of LibIDN2 installed.
  
  * Int **IDN2\_VERSION\_MINOR**
  
  The minor version of LidIDN2 installed.
  
  * Int **IDN2\_VERSION\_PATCH**
  
  The patch version of LibIDN2 installed.
  
  ## FLAGS
  
  * Int **IDN2\_NFC\_INPUT**
  
  Normalize the input string using the NFC format.
  
  * Int **IDN2\_ALABEL\_ROUNDTRIP**
  
  Perform optional IDNA2008 lookup roundtrip check.
  
  * Int **IDN2\_TRANSITIONAL**
  
  Perform Unicode TR46 transitional processing.
  
  * Int **IDN2\_NONTRANSITIONAL**
  
  Perform Unicode TR46 non-transitional processing.
  
  ## ERRORS
  
  * Int **IDN2\_OK**
  
  Success.
  
  * Int **IDN2\_MALLOC**
  
  Memory allocation failure.
  
  * Int **IDN2\_NO\_CODESET**
  
  Failed to determine a string's encoding.
  
  * Int **IDN2\_ICONV\_FAIL**
  
  Failed to transcode a string to UTF8.
  
  * Int **IDN2\_ENCODING\_ERROR**
  
  Unicode data encoding error.
  
  * Int **IDN2\_NFC**
  
  Failed to normalize a string.
  
  * Int **IDN2\_PUNYCODE\_BAD\_INPUT**
  
  Invalid input to Punycode.
  
  * Int **IDN2\_PUNYCODE\_BIG\_OUTPUT**
  
  Punycode output buffer is too small.
  
  * Int **IDN2\_PUNYCODE\_OVERFLOW**
  
  Punycode conversion would overflow.
  
  * Int **IDN2\_TOO\_BIG\_DOMAIN**
  
  Domain is larger than `IDN2_DOMAIN_MAX_LENGTH`.
  
  * Int **IDN2\_TOO\_BIG\_LABEL**
  
  Label is larger than `IDN2_LABEL_MAX_LENGTH`.
  
  * Int **IDN2\_INVALID\_ALABEL**
  
  Invalid A-label.
  
  * Int **IDN2\_UALABEL\_MISMATCH**
  
  Given U-label and A-label do not match.
  
  * Int **IDN2\_INVALID\_FLAGS**
  
  Invalid combination of flags.
  
  * Int **IDN2\_NOT\_NFC**
  
  String is not normalized in NFC format.
  
  * Int **IDN2\_2HYPHEN**
  
  String has forbidden two hyphens.
  
  * Int **IDN2\_HYPHEN\_STARTEND**
  
  String has forbidden start/end hyphen.
  
  * Int **IDN2\_LEADING\_COMBINING**
  
  String has forbidden leading combining character.
  
  * Int **IDN2\_DISALLOWED**
  
  String has disallowed character.
  
  * Int **IDN2\_CONTEXTJ**
  
  String has forbidden context-j character.
  
  * Int **IDN2\_CONTEXTJ\_NO\_RULE**
  
  String has context-j character without any rull.
  
  * Int **IDN2\_CONTEXTO**
  
  String has forbidden context-o character.
  
  * Int **IDN2\_CONTEXTO\_NO\_RULE**
  
  String has context-o character without any rull.
  
  * Int **IDN2\_UNASSIGNED**
  
  String has forbidden unassigned character.
  
  * Int **IDN2\_BIDI**
  
  String has forbidden bi-directional properties.
  
  * Int **IDN2\_DOT\_IN\_LABEL**
  
  Label has forbidden dot (TR46).
  
  * Int **IDN2\_INVALID\_TRANSITIONAL**
  
  Label has a character forbidden in transitional mode (TR46).
  
  * Int **IDN2\_INVALID\_NONTRANSITIONAL**
  
  Label has a character forbidden in non-transitional mode (TR46).
  
  # AUTHOR
  
  Ben Davies (kaiepi)
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2017 Ben Davies
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  