view release on metacpan or  search on metacpan

lib/Badger/URL.pm  view on Meta::CPAN

=head1 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

=head1 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 L<URI> module.

A URL looks like this:

     http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe
     \__/   \______________________/\___________/ \___________/ \____/
      |                |                  |             |          |
    scheme         authority             path         query     fragment

The C<authority> part can be broken down further:

     abw@badgerpower.com:8080
     \_/ \_____________/ \__/
      |         |         |
     user      host      port

A L<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

=head1 METHODS

=head2 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',
    );

=head2 copy()

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

    my $copy = $url->copy;

=head2 url()

Method to return the complete URL.

    print $url->url;
        # http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe