GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  BADGER::URL (3)

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS



    use Badger::URL;

    # all-in-one URL string
    my $url = Badger::URL->new(
        abw@badgerpower.com:8080/under/ground">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;    
        # abw@badgerpower.com:8080">http://abw@badgerpower.com:8080
   
    print $url->service;   
        # abw@badgerpower.com:8080/under/ground">http://abw@badgerpower.com:8080/under/ground
   
    print $url->request;   
        # abw@badgerpower.com:8080/under/ground">http://abw@badgerpower.com:8080/under/ground?animal=badger
   
    # method to return the whole URL
    print $url->url();
        # abw@badgerpower.com:8080/under/ground">http://abw@badgerpower.com:8080/under/ground?animal=badger#stripe
   
    # overloaded stringification operator calls url() method
    print $url;    
        # abw@badgerpower.com:8080/under/ground">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:



     abw@badgerpower.com:8080/under/ground">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(
        abw@badgerpower.com:8080/under/ground">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()

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;
        # abw@badgerpower.com:8080/under/ground">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();      
        # fred@example.org:1234">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();      
        # fred@example.org:1234/right/here">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();      
        # fred@example.org:1234/right/here">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
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 BADGER::URL (3) 2012-01-25

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.