.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "URI::ToDisk 3pm"
.TH URI::ToDisk 3pm "2021-01-02" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
URI::ToDisk \- An object for mapping a URI to an on\-disk storage directory
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # We have a directory on disk that is accessible via a web server
\&  my $authors = URI::ToDisk\->new( \*(Aq/var/www/AUTHORS\*(Aq, \*(Aqhttp://ali.as/AUTHORS\*(Aq );
\&  
\&  # We know where a particular generated file needs to go
\&  my $about = $authors\->catfile( \*(AqA\*(Aq, \*(AqAD\*(Aq, \*(AqADAMK\*(Aq, \*(Aqabout.html\*(Aq );
\&  
\&  # 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\en";
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1URL.\s0 From this location,
we should be able to derived both a filesystem path and \s-1URL\s0 for any given
directory or file under this location that we might need to work with.
.SS "Implementation"
.IX Subsection "Implementation"
Internally each \f(CW\*(C`URI::ToDisk\*(C'\fR object contains both a filesystem path, 
which is altered using File::Spec, and a \s-1URI\s0 object. When making a 
change, the path section of the \s-1URI\s0 is altered using <File::Spec::Unix>.
.SS "Method Calling Conventions"
.IX Subsection "Method Calling Conventions"
The main functional methods, such as \f(CW\*(C`catdir\*(C'\fR and \f(CW\*(C`catfile\*(C'\fR, do \fBnot\fR
modify the original object, instead returning a new object containing the
new location.
.PP
This means that it should be used in a somewhat similar way to File::Spec.
.PP
.Vb 3
\&  # The File::Spec way
\&  my $path = \*(Aq/some/path\*(Aq;
\&  $path = File::Spec\->catfile( $path, \*(Aqsome\*(Aq, \*(Aqfile.txt\*(Aq );
\&  
\&  # The URI::ToDisk way
\&  my $location = URI::ToDisk\->new( \*(Aq/some/path\*(Aq, \*(Aqhttp://foo.com/blah\*(Aq );
\&  $location = $location\->catfile( \*(Aqsome\*(Aq, \*(Aqfile.txt\*(Aq );
.Ve
.PP
\&\s-1OK,\s0 well it's not exactly \s-1THAT\s0 close, but you get the idea. It also allows you
to do method chaining, which is basically
.PP
.Vb 1
\&  URI::ToDisk\->new( \*(Aq/foo\*(Aq, \*(Aqhttp://foo.com/\*(Aq )\->catfile( \*(Aqbar.txt\*(Aq )\->uri
.Ve
.PP
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.
.PP
.Vb 5
\&  my $base = URI::ToDisk\->new( \*(Aq/my/cache\*(Aq, \*(Aqhttp://foo.com/\*(Aq );
\&  foreach my $path ( @some_files ) {
\&        my $file = $base\->catfile( $path );
\&        print $file\->path . \*(Aq: \*(Aq . $file\->uri . "\en";
\&  }
.Ve
.PP
In the above example, you don't have to be continuously cloning the location,
because all that stuff happens internally as needed.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "new $path, $http_url"
.el .SS "new \f(CW$path\fP, \f(CW$http_url\fP"
.IX Subsection "new $path, $http_url"
The \f(CW\*(C`new\*(C'\fR constructor takes as argument a filesystem path and a http(s) 
\&\s-1URL.\s0 Both are required, and the method will return \f(CW\*(C`undef\*(C'\fR is either is 
illegal. The \s-1URL\s0 is not required to have protocol, host or port sections,
and as such allows for host-relative \s-1URL\s0 to be used.
.PP
Returns a new \f(CW\*(C`URI::ToDisk\*(C'\fR object on success, or \f(CW\*(C`undef\*(C'\fR on failure.
.ie n .SS "param $various"
.el .SS "param \f(CW$various\fP"
.IX Subsection "param $various"
\&\f(CW\*(C`param\*(C'\fR 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, \f(CW$http_url\fR), or
a reference to an array containing the same two arguments.
.PP
Returns a URI::ToDisk if possible, or \f(CW\*(C`undef\*(C'\fR if one cannot be provided.
.SS "uri"
.IX Subsection "uri"
The \f(CW\*(C`uri\*(C'\fR method gets and returns the current \s-1URI\s0 of the location, in 
string form.
.SS "\s-1URI\s0"
.IX Subsection "URI"
The capitalised \f(CW\*(C`URI\*(C'\fR method gets and returns a copy of the raw \s-1URI\s0,
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.
.SS "path"
.IX Subsection "path"
The \f(CW\*(C`path\*(C'\fR method returns the filesystem path componant of the location.
.SS "catdir 'dir', 'dir', ..."
.IX Subsection "catdir 'dir', 'dir', ..."
A File::Spec workalike, the \f(CW\*(C`catdir\*(C'\fR method acts in the same way as for
File::Spec, modifying both componants of the location. The \f(CW\*(C`catdir\*(C'\fR method
returns a \fBnew\fR URI::ToDisk object representing the new location, or
\&\f(CW\*(C`undef\*(C'\fR on error.
.ie n .SS "catfile [ 'dir', ..., ] $file"
.el .SS "catfile [ 'dir', ..., ] \f(CW$file\fP"
.IX Subsection "catfile [ 'dir', ..., ] $file"
Like \f(CW\*(C`catdir\*(C'\fR, the \f(CW\*(C`catfile\*(C'\fR method acts in the same was as for 
File::Spec, and returns a new URI::ToDisk object representing 
the file, or \f(CW\*(C`undef\*(C'\fR on error.
.SH "TO DO"
.IX Header "TO DO"
Add more File::Spec\-y methods as needed. Ask if you need one.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs should be reported via the \s-1CPAN\s0 bug tracker at
.PP
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URI\-ToDisk>
.PP
For other issues, or commercial enhancement or support, contact the author.
.SH "AUTHORS"
.IX Header "AUTHORS"
Adam Kennedy <http://ali.as/>, cpan@ali.as
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003 \- 2006 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.