URI::ToDisk(3pm)

💖 URI::ToDisk 💖

okay bestie so this is URI::ToDisk — a whole module that lives in the User Contributed Perl Documentation and honestly? it's giving "one object, two worlds." you give it a spot on your disk and a URL, and it keeps them in sync so you never have to do the mental math again. no cap.

---

✨ SYNOPSIS ✨

# We have a directory on disk that is accessible via a web server
my $authors = URI::ToDisk->new( '/var/www/AUTHORS', 'http://ali.as/AUTHORS' );

# We know where a particular generated file needs to go
my $about = $authors->catfile( 'A', 'AD', 'ADAMK', 'about.html' );

# Save the file to disk
my $file = $about->path;
open( FILE, ">$file" ) or die "open: $!";
print FILE, $content;
close FILE;

# Show the user where to see the file
my $uri = $about->uri;
print "Author information is at $uri\n";

like. look at that. you got a folder, you got a URL, and catfile just… ✨hands you both✨. it's giving main character energy fr fr.

---

🌸 DESCRIPTION 🌸

so basically, in a bunch of web-adjacent processes, you lowkey need to keep track of a chunk of disk that maps to a particular URL. and from that one location you should be able to derive both a filesystem path and a URL for any directory or file underneath it. that's the whole vibe check.

🦋 Implementation

internally, every URI::ToDisk object is holding both:

• a filesystem path — which gets altered using File::Spec
• a URI object

and when you make a change, the path section of the URI gets altered using <File::Spec::Unix>. iconic behavior tbh. 💅

🎀 Method Calling Conventions

the main functional methods, like catdir and catfile, do not modify the original object. instead they hand you back a new object with the new location. not me being obsessed with immutability 🥰

which means you use it kinda-sorta similarly to File::Spec:

# The File::Spec way
my $path = '/some/path';
$path = File::Spec->catfile( $path, 'some', 'file.txt' );

# The URI::ToDisk way
my $location = URI::ToDisk->new( '/some/path', 'http://foo.com/blah' );
$location = $location->catfile( 'some', 'file.txt' );

okay so it's not exactly THAT close, but you get the idea bestie. it also lets you do method chaining, which is basically:

URI::ToDisk->new( '/foo', 'http://foo.com/' )->catfile( 'bar.txt' )->uri

which might seem a little trivial right now, but the author expects it to get more useful later. and it also means you can do stuff like this:

my $base = URI::ToDisk->new( '/my/cache', 'http://foo.com/' );
foreach my $path ( @some_files ) {
      my $file = $base->catfile( $path );
      print $file->path . ': ' . $file->uri . "\n";
}

in the above example you do not have to be continuously cloning the location, because all that stuff happens internally as needed. she's self-sufficient 💜

---

👑 METHODS 👑

⭐ new $path, $http_url

the new constructor takes as argument a filesystem path and a http(s) URL. both are required, and the method will return undef if either is illegal. the URL is not required to have protocol, host or port sections, and as such allows for host-relative URL to be used.

returns a new URI::ToDisk object on success, or undef on failure.

so yeah, if you feed her something illegal she just goes undef. no drama, just silence 💀

⭐ param $various

param is provided as a mechanism for higher order modules to flexibly accept URI::ToDisk's as parameters. in this case, it accepts either:

• an existing URI::ToDisk object
• two arguments ($path, $http_url)
• or a reference to an array containing the same two arguments

returns a URI::ToDisk if possible, or undef if one cannot be provided.

⭐ uri

the uri method gets and returns the current URI of the location, in string form. 🦋

⭐ URI

the capitalised URI method gets and returns a copy of the raw URI, held internally by the location. note that only a copy is returned, and as such as safe to further modify yourself without effecting the location. go off, edit it, she won't feel a thing ✨

⭐ path

the path method returns the filesystem path componant of the location.

⭐ catdir 'dir', 'dir', ...

a File::Spec workalike — the catdir method acts in the same way as for File::Spec, modifying both componants of the location. the catdir method returns a new URI::ToDisk object representing the new location, or undef on error.

⭐ catfile [ 'dir', ..., ] $file

like catdir, the catfile method acts in the same was as for File::Spec, and returns a new URI::ToDisk object representing the file, or undef on error.

---

🌈 TO DO 🌈

add more File::Spec-y methods as needed. ask if you need one. (she's taking requests, periodt.)

---

🫶 SUPPORT 🫶

bugs should be reported via the CPAN bug tracker at

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI-ToDisk>

for other issues, or commercial enhancement or support, contact the author.

---

💜 AUTHORS 💜

Adam Kennedy <http://ali.as/>, cpan@ali.as

---

🎀 COPYRIGHT 🎀

Copyright (c) 2003 - 2006 Adam Kennedy.

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

the full text of the license can be found in the LICENSE file included with this module.

---

okay that's the whole page bestie, you ate 💅 and just so you know, this was perl v5.36.0, dated 2022-12-12, and it's the URI::ToDisk(3pm) manual page — go forth and map those URIs to disk, iykyk 💖✨🌸