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.htmlVERSION
0.03
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