Internationalized domain names (UTS #46).
to_ascii/1 turns a domain name into the ASCII form that DNS uses, encoding non-ASCII labels
with Punycode. to_unicode/1 turns it back into Unicode for display. Both map the name first:
case folding, normalization, and the UTS #46 mapping table, so "BÜCHER.example" and
"bücher.example" give the same result.
Processing is nontransitional, with every check on: STD3 ASCII rules, hyphens, CONTEXTJ, bidi, and label and domain length.
These functions need the :idna feature. Without it they return or raise Mojibake.Error with
reason :feature_not_enabled.
Summary
Functions
Process domain into its :ascii or :unicode form and return the result with the list of
validation errors, which is empty for a valid name. The result is a best effort when there are
errors: show it to people if you like, but never look it up.
Convert domain to its ASCII form.
Like to_ascii/1, but raises Mojibake.Error.
Convert domain to its Unicode form, decoding Punycode labels.
Like to_unicode/1, but raises Mojibake.Error.
Types
@type error() ::
:punycode
| :empty_label
| :hyphen
| :not_nfc
| :leading_mark
| :disallowed
| :std3
| :contextj
| :bidi
| :label_length
| :domain_length
A UTS #46 validation error:
:punycode- anxn--label is not valid Punycode:empty_label- a label is empty, as in "a..b":hyphen- a label starts or ends with a hyphen, or has hyphens in positions 3 and 4:not_nfc- a label is not in NFC:leading_mark- a label starts with a combining mark:disallowed- a character is not allowed in domain names:std3- a character breaks the STD3 ASCII rules, such as "_":contextj- a ZERO WIDTH JOINER or NON-JOINER is in the wrong context:bidi- the name breaks the bidi rules of RFC 5893:label_length- a label is longer than 63 bytes in ASCII form:domain_length- the name is longer than 253 bytes in ASCII form
Functions
Process domain into its :ascii or :unicode form and return the result with the list of
validation errors, which is empty for a valid name. The result is a best effort when there are
errors: show it to people if you like, but never look it up.
Raises Mojibake.Error if domain is not well-formed UTF-8.
Examples
iex> Mojibake.IDNA.process("a..Example", :unicode)
{"a..example", [:empty_label]}
iex> Mojibake.IDNA.process("ok.example", :ascii)
{"ok.example", []}
@spec to_ascii(String.t()) :: {:ok, String.t()} | {:error, Mojibake.Error.t()}
Convert domain to its ASCII form.
Returns {:error, %Mojibake.Error{reason: :invalid_domain, detail: errors}} with the list of
error/0 if the name is not valid. Do not look up an invalid name.
Examples
iex> Mojibake.IDNA.to_ascii("Bücher.example")
{:ok, "xn--bcher-kva.example"}
iex> {:error, error} = Mojibake.IDNA.to_ascii("-bad-.example")
iex> error.detail
[:hyphen]
Like to_ascii/1, but raises Mojibake.Error.
Examples
iex> Mojibake.IDNA.to_ascii!("例え.テスト")
"xn--r8jz45g.xn--zckzah"
@spec to_unicode(String.t()) :: {:ok, String.t()} | {:error, Mojibake.Error.t()}
Convert domain to its Unicode form, decoding Punycode labels.
Returns {:error, %Mojibake.Error{reason: :invalid_domain, detail: errors}} if the name is not
valid. process/2 returns the converted name even then.
Examples
iex> Mojibake.IDNA.to_unicode("xn--bcher-kva.example")
{:ok, "bücher.example"}
iex> Mojibake.IDNA.to_unicode("WWW.Example.COM")
{:ok, "www.example.com"}
Like to_unicode/1, but raises Mojibake.Error.
Examples
iex> Mojibake.IDNA.to_unicode!("xn--r8jz45g.xn--zckzah")
"例え.テスト"