=head1 NAME

Web::URL - URL record API

=head1 SYNOPSIS

  use Web::URL;
  my $url = Web::URL->parse_string ($input_string, $base_url_record);
  warn $url->stringify;

=head1 SYNOPSIS

The C<Web::URL> object represents a URL record.

=head1 METHODS

There are following methods:

=over 4

=item $url = Web::URL->parse_string ($input_string, $base_url_record)

Parse a string and return a URL record object (L<Web::URL>) for it.

The first argument is the string to be parsed as a URL string.

The second argument is a URL record, which is used as the base URL.
If C<undef> is specified, C<about:blank> is used as the base URL.

If the parsing failed, the method returns C<undef>.

=item $string = $url->scheme

Return the scheme component of the URL, canonicalized (i.e. in
lowercase).

=item $boolean = $url->is_http_s

Return whether the URL's scheme is an HTTP(S) scheme or not,
i.e. whether either C<http> or C<https> or not.

=item $string = $url->username

Return the username component of the URL.  If the URL has no explicit
username component, the empty string is returned.

=item $string = $url->password

Return the password component of the URL.  If the URL has no explicit
password component, the empty string is returned.

=item $host = $url->host

Return the host (L<Web::Host>) of the URL, if any, or C<undef>.

=item $string = $url->port

Return the port component of the URL, if any, or C<undef>.

=item $string = $url->hostport

Serialize the host and port components of the URL, if any, or
C<undef>.

=item $string = $url->path

Serialize the path component of the URL.

=item $string = $url->pathquery

Serialize the path and query components of the URL.

=item $string = $url->query

Return the query component of the URL, if any, or C<undef>.  It does
not contain any C<?> prefix.

=item $url->set_query_params ($params, append => $boolean)

Set the query parameters, in the C<application/x-www-form-urlencoded>
syntax with UTF-8.

If the C<append> flag is set to a true value, any existing query
component of the URL is preserved and the parameters are appended with
separator C<&>.

If the C<append> flag is set to a false value, any existing query
component of the URL is discarded.

This method mutates the URL record object.

=item $string = $url->fragment

Return the fragment component of the URL, if any, or C<undef>.  It
does not contain any C<#> prefix.

=item $origin = $url->get_origin

Get a new origin object (L<Web::Origin>) representing the origin of
the URL.

=item $string = $url->stringify

=item $string = $url->TO_JSON

Serialize the URL record as a string.

=item $string = $url->stringify_without_fragment

Serialize the URL record as a string, excluding any fragment
component.

=item $string = $url->originpathquery

Serialize the URL record as a string, excluding any C<userinfo> and
fragment components.

This method can be used to obtain a value for HTTP request-target or
C<Referer:> and C<document.referrer>.

=item $string = $url->originpath

Serialize the URL record as a string, excluding any C<userinfo>,
query, and fragment components.

This method can be used to obtain a value for OAuth 1.0 signature
generation.

=item $url2 = $url->clone

Create another URL record object which has the same components as the
URL record.

=back

=head1 SPECIFICATION

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

However, the URL parsing does not support URL Standard yet; the old
spec implemented by the current version of the URL parser module is
available at
<https://github.com/wakaba/tests-web-url/blob/master/spec.txt>.

=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