Badger::URL(3pm)

💖 Badger::URL 💖

okay bestie, so this is Badger::URL — it's the User Contributed Perl Documentation page for it, section 3pm, and it's literally the moment your Perl code learns what a URL even is. it's giving glow-up for web programming ✨

---

✨ NAME ✨

Badger::URL — representation of a Uniform Resource Locator (URL) 🦋

like. a URL. as an object. that you can poke at and rearrange. slay.

---

✨ 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

no cap, you can build a whole URL from one string OR from a lil named-params situation and both ate 💅

---

✨ DESCRIPTION ✨

so this module implements an object for representing URLs. it can parse existing URLs to break them down into their constituent parts, and also generate new or modified URLs. iconic behaviour honestly.

the emphasis is on simplicity and convenience for tasks related to web programming — like dispatching web applications based on the URL, generating URLs for redirects, or embedding them as links in HTML pages. that's the vibe check 🎀

okay so if you want more generic URI functionality, you should lowkey consider using the URI module instead. just saying. iykyk.

a URL looks like this:

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

and the "authority" part? it can be broken down even further, bestie:

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

a Badger::URL object will parse a URL and store the component parts internally. then you can change any of the individual parts and regenerate the URL. it's giving lego but for URLs 🧚

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. main character energy fr fr.

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. a lil clone, a twin, a doppelgänger 🦋

my $copy = $url->copy;

🌸 url()

method to return the complete URL. the whole thing. the entire meal.

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. same energy, different name 💅

🌸 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. it's the whole lil ensemble cast.

$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. the scenic route 🍓

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

🌸 query()

get or set the query part of the URL. heads up bestie: the leading '"?"' is not considered part of the query and should be should not be included when setting a new query. so don't add it, okay? 🙈

$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. same deal as query, bestie: 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. two ingredients, one slay ✨

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. no need to stress about it 💜

my $base = Badger::URL->new('http://badgerpower.com/example');
my $rel  = $base->absolute('foo/bar');

print $rel;     # http://badgerpower.com/foo/bar

---

🔧 INTERNAL METHODS 🔧

these are the behind-the-scenes girlies. the stage crew. you probably don't need to touch them but here they are in all their glory 👑

🎀 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. it's giving X-ray vision 🔥

---

🎁 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. either way you get a URL out of it 💖

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

---

and that's the whole page bestie, we ate and left no crumbs 💅✨ this was Badger::URL, perl v5.36.0, dated 2023-08-28 — go forth and parse some URLs, you absolute icon 👑🦋💖