Badger::URL

NAME

Top Close Open

Badger::URL - representation of a Uniform Resource Locator (URL)

SYNOPSIS

Top Close Open
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

Top Close Open

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

Top Close Open

new($url)

Top Close Open

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

my $url = Badger::URL->new(
    scheme      => 'http',
    user        => 'abw',
    host        => 'badgerpower.com',
    port        => '8080',
    path        => '/under/ground',
    query       => 'animal=badger',
    fragment    => 'stripe',
);

copy()

Top Close Open

This method creates and returns a new Badger::URL object as a copy of the current one.

my $copy = $url->copy;

url()

Top Close Open

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()

Top Close Open

An alias for the url() method.

scheme()

Top Close Open

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()

Top Close Open

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()

Top Close Open

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()

Top Close Open

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()

Top Close Open

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()

Top Close Open

Get or set the path part of the URL.

$url->path('/right/here');
print $url->path();         # /right/here

query()

Top Close Open

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()

Top Close Open

Get or set the query parameters.

# get params
my $params = $url->params;

# set params
$url->params(
    x => 10
);

fragment()

Top Close Open

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()

Top Close Open

Returns a composite of the scheme and authority.

print $url->server();       
    # http://fred@example.org:1234

service()

Top Close Open

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()

Top Close Open

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)

Top Close Open

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)

Top Close Open

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

Top Close Open

set($items)

Top Close Open

This method is used to set internal values.

join_authority()

Top Close Open

This method reconstructs the authority from the host, port and user.

join_query()

Top Close Open

This method reconstructs the query from the query parameters.

join_url()

Top Close Open

This method reconstructs the complete URL from its constituent parts.

split_authority()

Top Close Open

This method splits the authority into host, port and user.

split_query()

Top Close Open

This method splits the query string into query parameters.

dump()

Top Close Open

Return a text representation of the structure of the URL object, for debugging purposes.

EXPORTABLE SUBROUTINES

Top Close Open

URL($url)

Top Close Open

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

Top Close Open

Andy Wardley http://wardley.org/

COPYRIGHT

Top Close Open

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

Top Close Open

URI

Fork Me on Github