URI::SmartURI(3pm)

💖 URI::SmartURI(3pm) 💖

URI::SmartURI — fresh out of the User Contributed Perl Documentation, section 3pm. Bestie, we are SO back 🫶

---

✨ NAME ✨

URI::SmartURI — subclassable and hostless URIs ✨

🎀 VERSION 🎀

Version 0.032 💅

🌈 SYNOPSIS 🌈

my $uri = URI::SmartURI->new(
    'http://host/foo/',
    { reference => 'http://host/bar/' }
);

my $hostless = $uri->hostless; # '/foo/'

$hostless->absolute; # 'http://host/foo/'

$uri->relative; # '../foo/'

🦋 DESCRIPTION 🦋

okay so, this is a sort of "subclass" of URI, except it's doing it via delegation, and it's got some extra methods bolted on top. The important part: every single method that works for URIs works on these objects too. All of them. No cap, fr fr.

It's similar in spirit to URI::WithBase. Same energy, different font 💜

And it's also completely safe to subclass for your own use. Go off, build your little thing, the vibes are immaculate.

---

🧚 CONSTRUCTORS 🧚

URI::SmartURI->new($str, [$scheme|{reference => $ref, scheme => $scheme}])

Takes a uri $str, plus optionally a $scheme, OR a hashref carrying a reference uri (used for computing relative/absolute URIs) and an optional scheme. Your choice, she's flexible ✨

my $uri = URI::SmartURI->new('http://dev.catalyst.perl.org/');

my $uri = URI::SmartURI->new('/dev.catalyst.perl.org/new-wiki/', 'http');

my $uri = URI::SmartURI->new(
    'http://search.cpan.org/~jrockway/Catalyst-Manual-5.701003/',
    { reference => 'http://search.cpan.org/' }
);

The object you get back is blessed into a scheme-specific subclass, picked based on the class of the underlying $uri->obj (that's the URI object). So for example URI::SmartURI::http, which derives from URI::SmartURI — or from $uri->factory_class if you're out here subclassing 👑

URI::SmartURI->new_abs($str, $base_uri)

Proxy for URI->new_abs 🫶

URI::SmartURI->newlocal($filename, [$os])

Proxy for URI::URL->newlocal 🫶

---

💅 METHODS 💅

• $uri->hostless — hands you the URI with the scheme and host parts stripped. That's it. That's the girl.
• $uri->reference — accessor for the reference URI (used by relative/absolute below).
• $uri->relative — returns the URI relative to the reference URI.
• $uri->absolute — returns the absolute URI, using the reference URI as the base.
• "" — stringification works, just like with URIs. She's stringifiable, she's that girl.
• == — and == does as well. Equality goes hard too.
• $uri->eq($other_uri) — explicit equality check against another URI. You can also call it as URI::SmartURI::eq($uri1, $uri2), whichever feels right.
• $uri->obj — accessor for the URI object that methods are delegated to. This is where all the actual delegating happens.
• $uri->factory_class — the class whose constructor was called to make the $uri object, usually URI::SmartURI or your own subclass. This is what's used to call class (rather than object) methods. Lowkey important for subclasses.

🔧 INTERNAL METHODS 🔧

These are used internally by SmartURI, so they're not interesting for general use — but they may be useful for writing subclasses. Plumbing, basically. iykyk.

• $uri->_opts — returns a hashref of options for the $uri (reference and scheme).
• $class->_resolve_uri_class($uri_class) — converts, eg., URI::http to URI::SmartURI::http.
• $class->_make_uri_class($uri_class) — creates a new proxy class for a URI class, with all exports and constructor intact, and returns its name, which is built using _resolve_uri_class (above).
• $class->_inflate_uris(\@rray, $opts) — inflates any URI objects in @rray into URI::SmartURI objects; everything else passes through unharmed. $opts is a hashref of options to include in the objects created.
• $class->_deflate_uris(@rray) — deflates any URI::SmartURI objects in @rray into the URI objects they're proxies for; everything else passes through unharmed.

🫶 friendly heads up: yes, the docs really do spell it \@rray and @rray. That's not me being cute, that's verbatim. Do not @ me.

---

🪄 MAGICAL IMPORT 🪄

On import with the -import_uri_mods flag, it loads all the URI .pms into your class namespace. Magical. Iconic. Unhinged, a little.

This works:

use URI::SmartURI '-import_uri_mods';
use URI::SmartURI::WithBase;
use URI::SmartURI::URL;

my $url = URI::SmartURI::URL->new(...); # URI::URL proxy

Even this works:

use URI::SmartURI '-import_uri_mods';
use URI::SmartURI::Escape qw(%escapes);

It even works with a subclass of URI::SmartURI.

Real talk from the author: he only wrote this functionality so that he could run the URI test suite without much modification — it has no real practical value 😭 iconic honesty tbh.

💀 BUGS 💀

Please report any bugs or feature requests to bug-uri-smarturi at rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI-SmartURI>. He will be notified, and then you'll automatically be notified of progress on your bug as he makes changes. Mutual notification situation, we love a feedback loop 🫶

🍓 SUPPORT 🍓

You can find documentation for this module with the perldoc command.

perldoc URI::SmartURI

You can also look for information at:

• RT: CPAN's request tracker — <http://rt.cpan.org/NoAuth/Bugs.html?Dist=URI-SmartURI>
• AnnoCPAN: Annotated CPAN documentation — <http://annocpan.org/dist/URI-SmartURI>
• CPAN Ratings — <http://cpanratings.perl.org/d/URI-SmartURI>
• Search CPAN — <http://search.cpan.org/dist/URI-SmartURI>

👀 SEE ALSO 👀

Catalyst::Plugin::SmartURI, URI, URI::WithBase 🌸

🌟 ACKNOWLEDGEMENTS 🌟

Thanks to the folks on freenode #perl for helping him out when he was getting stuck — Somni, revdiablo, PerlJam and others whose nicks he forgets. Shoutout to the nicks that got away 😭💜

👑 AUTHOR 👑

Rafael Kitover, <rkitover at cpan.org> ✨

📜 COPYRIGHT & LICENSE 📜

Copyright (c) 2008 Rafael Kitover

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 💖 This one's perl v5.36.0, dated 2022-12-12 — and yes, the manual name up top was URI::SmartURI(3pm) from the User Contributed Perl Documentation. mwah, go read your URIs 🌈🦋✨