Provided by: libbadger-perl_0.16-2_all 
NAME
Badger::URL - representation of a Uniform Resource Locator (URL)
SYNOPSIS
use Badger::URL;
# all-in-one URL string
my $url = Badger::URL->new(
'http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe'
);
# named parameters
my $url = Badger::URL->new(
scheme => 'http',
user => 'abw',
host => 'badgerpower.com',
port => '8080',
path => '/under/ground',
query => 'animal=badger',
fragment => 'stripe',
);
# methods to access standard W3C parts of URL
print $url->scheme; # http
print $url->authority; # abw@badgerpower.com:8080
print $url->user; # abw
print $url->host; # badgerpower.com
print $url->port; # 8080
print $url->path; # /under/ground
print $url->query; # animal=badger
print $uri->fragment; # stripe
# additional composite methods:
print $url->server;
# http://abw@badgerpower.com:8080
print $url->service;
# http://abw@badgerpower.com:8080/under/ground
print $url->request;
# http://abw@badgerpower.com:8080/under/ground?animal=badger
# method to return the whole URL
print $url->url();
# http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe
# overloaded stringification operator calls url() method
print $url;
# http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe
DESCRIPTION
This module implements an object for representing URLs. It can parse existing URLs to
break them down into their constituent parts, and also to generate new or modified URLs.
The emphasis is on simplicity and convenience for tasks related to web programming (e.g.
dispatching web applications based on the URL, generating URLs for redirects or embedding
as links in HTML pages). If you want more generic URI functionality then you should
consider using the URI module.
A URL looks like this:
http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe
\__/ \______________________/\___________/ \___________/ \____/
| | | | |
scheme authority path query fragment
The "authority" part can be broken down further:
abw@badgerpower.com:8080
\_/ \_____________/ \__/
| | |
user host port
A Badger::URL object will parse a URL and store the component parts internally. You can
then change any of the individual parts and regenerate the URL.
my $url = Badger::URL->new(
'http://badgerpower.com/'
);
$url->port('8080');
$url->path('/under/ground');
$url->query('animal=badger');
print $url; # http://badgerpower.com:8080/under/ground?animal=badger
METHODS
new($url)
This constructor method is used to create a new URL object.
my $url = Badger::URL->new(
'http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe'
);
You can also specify the individual parts of the URL using named parameters.
my $url = Badger::URL->new(
scheme => 'http',
user => 'abw',
host => 'badgerpower.com',
port => '8080',
path => '/under/ground',
query => 'animal=badger',
fragment => 'stripe',
);
copy()
This method creates and returns a new "Badger::URL" object as a copy of the current one.
my $copy = $url->copy;
url()
Method to return the complete URL.
print $url->url;
# http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe
This method is called automatically whenever the URL object is stringified.
print $url; # same as above
text()
An alias for the url() method.
scheme()
Method to get or set the scheme part of the URL.
$url = Badger::URL->new('http://badgerpower.com/);
print $url->scheme(); # http
$url->scheme('ftp');
print $url->scheme(); # ftp
authority()
Method to get or set the authority part of the URL. This is comprised of a host with
optional user and/or port.
$url->authority('badgerpower.com');
$url->authority('abw@badgerpower.com');
$url->authority('badgerpower.com:8080');
$url->authority('abw@badgerpower.com:8080');
print $url->authority(); # abw@badgerpower.com:8080
user()
Method to get or set the optional user in the authority part of the URL.
$url->user('fred');
print $url->user(); # fred
print $url->authority(); # fred@badgerpower.com:8080
host()
Get or set the host in the authority part of the URL.
$url->host('example.org');
print $url->host(); # example.org
print $url->authority(); # fred@example.org:8080
port()
Get or set the port in the authority part of the URL.
$url->port(1234);
print $url->port(); # 1234
print $url->authority(); # fred@example.org:1234
path()
Get or set the path part of the URL.
$url->path('/right/here');
print $url->path(); # /right/here
query()
Get or set the query part of the URL. The leading '"?"' is not considered part of the
query and should be should not be included when setting a new query.
$url->query('animal=ferret');
print $url->query(); # animal=ferret
params()
Get or set the query parameters.
# get params
my $params = $url->params;
# set params
$url->params(
x => 10
);
fragment()
Get or set the fragment part of the URL. The leading '#' is not considered part of the
fragment and should be should not be included when setting a new fragment.
$url->fragment('feet');
print $url->fragment(); # feet
server()
Returns a composite of the scheme and authority.
print $url->server();
# http://fred@example.org:1234
service()
Returns a composite of the server (scheme and authority) and path (in other words,
everything up to the query or fragment).
print $url->server();
# http://fred@example.org:1234/right/here
request()
Returns a composite of the service (scheme, authority and path) and query (in other words,
everything except the fragment).
print $url->request();
# http://fred@example.org:1234/right/here?animal=badger
relative($path)
Returns a new URL with the relative path specified.
my $base = Badger::URL->new('http://badgerpower.com/example');
my $rel = $base->relative('foo/bar');
print $rel; # http://badgerpower.com/example/foo/bar
absolute($path)
Returns a new URL with the absolute path specified. The leading "/" on the path provided
as an argument is option. It will be assumed if not present.
my $base = Badger::URL->new('http://badgerpower.com/example');
my $rel = $base->absolute('foo/bar');
print $rel; # http://badgerpower.com/foo/bar
INTERNAL METHODS
set($items)
This method is used to set internal values.
join_authority()
This method reconstructs the "authority" from the "host", "port" and "user".
join_query()
This method reconstructs the "query" from the query parameters.
join_url()
This method reconstructs the complete URL from its constituent parts.
split_authority()
This method splits the "authority" into "host", "port" and "user".
split_query()
This method splits the "query" string into query parameters.
dump()
Return a text representation of the structure of the URL object, for debugging purposes.
EXPORTABLE SUBROUTINES
URL($url)
This constructor function can be used to create a new URL. If the argument is already a
"Badger::URL" object then it is copied to create a new object. Otherwise a new
"Badger::URL" object is created from scratch.
use Badger::URL 'URL';
my $url1 = URL('http://example.com/foo');
my $url2 = URL($url1);
AUTHOR
Andy Wardley <http://wardley.org/>
COPYRIGHT
Copyright (C) 2001-2010 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
SEE ALSO
URI