NAME
    URI::Builder - URI objects optimised for manipulation

SYNOPSIS
        my $uri = URI::Builder->new(
            scheme => 'http',
            host   => 'www.cpan.org',
        );

        $uri->path_segments(qw( misc cpan-faq.html ));

        say $uri->as_string; # http://www.cpan.org/misc/cpan-faq.html

VERSION
    0.02

DESCRIPTION
    This class is a close relative of URI, but while that class is optimised
    for parsing, this is optimised for building up or modifying URIs. To
    that end objects of this class represent their URIs in sections, each of
    which are independently mutable, that then need to be serialised to form
    a string. In contrast, "URI" uses a fully-formed string internally which
    must be parsed afresh each time a mutation is performed on it.

    At the moment only http and https URIs are known to work correctly,
    support for other schemes may follow later.

ATTRIBUTES
    The following attributes relate closely with the URI methods of the same
    names.

    *   scheme

    *   userinfo

    *   host

    *   port

    *   path_segments

    *   query_form

    *   query_keywords

    *   fragment

    In addition the "query_separator" attribute defines how "query_form"
    fields are joined. It defaults to ';' but can be usefully set to '&'.

    The accessors for these attributes have a similar interface to the URI
    methods, that is to say that they return old values when new ones are
    set. Those attributes that take a list of values: "path_segments",
    "query_form" and "query_keywords" all return plain lists but can be
    passed nested array references.

METHODS
  new
    The constructor.

    In addition to the attributes listed above, a "uri" argument can be
    passed as a string or a URI object, which will be parsed to popoulate
    any missing fields.

        # a cpan URL without its path
        my $uri = URI::Builder->new(
            uri => 'http://www.cpan.org/SITES.html',
            path_segments => [],
        );

    Non-attribute arguments that match other methods in the class will cause
    those methods to be called on the object. This means that what we
    internally regard as composite attributes can be specified directly in
    the constructor.

        # Implicitly populate path_segments:
        my $uri = URI::Builder->new( path => 'relative/path' );

    Unrecognised arguments cause an exception.

  abs
        $absolute_uri = $relative_uri->abs($base_uri)

    Returns a new URI::Builder object as an absolute URL based on the given
    base URI.

    Implemented as a wrapper of "abs" in URI.

  rel
        $relative_uri = $absolute_uri->rel($base_uri)

    Returns a new URI::Builder object denoting the relative URI compared
    with the base URI.

    Implemented as a wrapper of "rel" in URI.

  clone
    Returns a new object with all attributes copied.

  as_string
    Returns the URI described by the object as a string. This is built up
    from the individual components each time it's called.

    This is also used as the stringification overload.

  uri
    Returns a version of this object as a URI object.

  default_port
    Returns the default port for the current object's scheme. This is
    obtained from the appropriate URI subclass. See "default_port" in URI.

  secure
    Returns true if the current scheme is a secure one, false otherwise. See
    "secure" in URI.

  authority
    Returns the 'authority' section of the URI. In our case this is obtained
    by combining "userinfo", "host" and "port" together as appropriate.

    Note that this is a read-only operation.

  host_port
    Returns the host and port in a single string.

  path
    Returns the path portion of the URI as a string.

    Can be assigned to to populate "path_segments".

    Leading, trailing and doubled slashes are represented faithfully using
    empty path segments.

  query
    Returns a string representation of the query. This is obtained from
    either "query_form" or "query_keywords", in that order.

    If an argument is passed, it is parsed to populate "query_form".

  path_query
  query_param
        @keys       = $uri->query_param
        @values     = $uri->query_param($key)
        @old_values = $uri->query_param($key, @new_values);

    This works exactly like the method of the same name implemented in
    URI::QueryParam.

    With no arguments, all unique query field names are returned

    With one argument, all values for the given field name are returned

    With more than one argument, values for the given key (first argument)
    are set to the given values (remaining arguments). Care is taken in this
    case to preserve the ordering of the fields.

  query_param_append
        $uri->query_param_append($key, @values)

    Appends fields to the end of the "query_form". Returns nothing.

  query_param_delete
        @old_values = $uri->query_param_delete($key)

    Removes all fields with the given key from the "query_form".

  query_form_hash
        $hashref     = $uri->query_form_hash
        $old_hashref = $uri->query_form_hash(\%new_hashref)

    A hash representation of the "query_form", with multiple values
    represented as arrayrefs.

TODO
    The following URI methods are currently not implemented:

    *   as_iri

    *   ihost