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.04

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
   Returns a string representation of the path plus the query string. See
   "path_query" in URI.

 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

LICENSE
   perlartistic

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.