=head1 NAME

Web::Host - Host names for the Web

=head1 SYNOPSIS

  use Web::Host;
  $host = Web::Host->parse_string ("MyDomain.test");
  warn $host->is_domain;
  warn $host->is_ip;
  warn $host->to_ascii;
  warn $host->to_unicode;

=head1 DESCRIPTION

The C<Web::Host> object represents a host, i.e. a domain, an IPv4
address, or an IPv6 address.

=head1 METHODS

Following methods are available:

=over 4

=item $host = Web::Host->parse_string ($string)

Parse the string and return a C<Web::Host> object for the host.  The
argument must be a domain, an IPv4 address, or an IPv6 address
enclosed by C<[> and C<]>.  It does not have to be canonicalized.  It
can be an IDN.  If the argument is not a valid host, an C<undef> value
is returned instead.

=item ($host, $port) = Web::Host->parse_hostport_string ($string)

Parse the string as a host optionally followed by C<:> and port number
and return a pair of a C<Web::Host> object for the host and an integer
for the port.  If the argument is not a valid host and port string, an
C<undef> and C<undef> pair is returned instead.

=item $host = Web::Host->new_from_packed_addr ($bytes)

Create a C<Web::Host> object for the "packed" IP address.  The
argument must be a byte string of length 4 or 16.  See also
C<packed_addr>.

=item $boolean = $host->is_domain

Return whether the host is a domain or not.

=item $boolean = $host->is_ip

Return whether the host is an IP address or not.

=item $boolean = $host->is_ipv4

Return whether the host is an IPv4 address or not.

=item $boolean = $host->is_ipv6

Return whether the host is an IPv6 address or not.

=item $host1->equals ($host2)

Return whether two hosts are equal or not.  They are equal if and only
if their serializations are equal, by definition.

=item $string = $host->stringify

=item $string = $host->to_ascii

=item $string = $host->TO_JSON

Serialize the host, using the host serializer of the URL Standard.
The result is canonicalized.  Any IDN is converted into its Punycode
form.  IPv6 addresses are enclosed in C<[> and C<]>.

Note that JavaScript code C<URL.domainToASCII ($domain)> (where
I<$domain> is a Unicode string) is equivalent to the following code:

  my $host = Web::Host->parse_string ($domain);
  if ($host->is_domain) {
    return $host->to_ascii;
  } else {
    return '';
  }

=item $string = $host->to_unicode

Serialize the host, but decode Punycode-encoded labels in the host
whenever possible.

Note that JavaScript code C<URL.domainToUnicode ($domain)> (where
I<$domain> is a Unicode string) is equivalent to the following code:

  my $host = Web::Host->parse_string ($domain);
  if ($host->is_domain) {
    return $host->to_unicode;
  } else {
    return '';
  }

=item $bytes = $host->packed_addr

Return the "packed" representation of the IP address, i.e. bytes of
length 4 (if IPv4 address) or 16 (if IPv6 address) representing the
address in network byte order (big endian).  If the host is a domain,
C<undef> is returned instead.

=item $string = $host->text_addr

Return the textual representation of the IP address, serialized using
the IPv4 or IPv6 serializer of the URL Standard.  The result is
canonicalized.  IPv6 addresses are I<not> enclosed by C<[> and C<]>.
If the host is a domain, C<undef> is returned instead.

=back

=head1 SPECIFICATIONS

URL Standard <https://url.spec.whatwg.org/>.

UTS #46: Unicode IDNA Compatibility Processing
<https://www.unicode.org/reports/tr46/>.

=head1 AUTHOR

Wakaba <wakaba@suikawiki.org>.

=head1 LICENSE

Copyright 2016-2017 Wakaba <wakaba@suikawiki.org>.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut