---
name: "URI::ToDisk"
section: "3pm"
platform: "linux"
package: "liburi-todisk-perl"
version: "1.12-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/URI::ToDisk"
---

# URI::ToDisk(3pm)

An object for mapping a URI to an on-disk storage directory

## NAME

URI::ToDisk - An object for mapping a URI to an on-disk storage directory

## 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";
```

## DESCRIPTION

In several process relating to working with the web, we may need to keep track of an area of disk that maps to a particular URL. From this location, we should be able to derived both a filesystem path and URL for any given directory or file under this location that we might need to work with.

### Implementation

Internally each `"URI::ToDisk"` object contains both a filesystem path,  which is altered using File::Spec, and a URI object. When making a  change, the path section of the URI is altered using \<File::Spec::Unix\>.

### Method Calling Conventions

The main functional methods, such as `"catdir"` and `"catfile"`, do **not** modify the original object, instead returning a new object containing the new location.

This means that it should be used in a somewhat similar way 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' );
```

OK, well it's not exactly THAT close, but you get the idea. It also allows you to do method chaining, which is basically

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

Which may seem a little trivial now, but I expect it to get more useful later. It also means you can do things 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 don't have to be continuously cloning the location, because all that stuff happens internally as needed.

## 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"` is 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.

### 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.

### 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.

## 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.