NAME
    HTML::Location - Working with disk to URI file mappings (deprecated: see
    URI::ToDisk)

STATUS
    As correctly noted by several users, "HTML::Location" is a really stupid
    name for this module. I apologise, I was new to the whole CPAN game at
    the time I first wrote it.

    This module has been relocated to URI::ToDisk. This module will remain
    indefinately for back-compatibility, but should otherwise be considered
    deprecated.

    Please convert your code to the otherwise identical URI::ToDisk at your
    leisure.

SYNOPSIS
      # We have a directory on disk that is accessible via a web server
      my $authors = HTML::Location->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 "HTML::Location" 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 HTML::Location way
      my $location = HTML::Location->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

      HTML::Location->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 = HTML::Location->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 "HTML::Location" object on success, or "undef" on failure.

  param $various
    "param" is provided as a mechanism for higher order modules to flexibly
    accept HTML::Location's as parameters. In this case, it accepts either
    an existing HTML::Location object, two arguments ($path, $http_url), or
    a reference to an array containing the same two arguments.

    Returns a HTML::Location 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 HTML::Location 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 HTML::Location 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=HTML-Location>

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

AUTHOR
    Adam Kennedy <adamk@cpan.org>

COPYRIGHT
    Copyright 2003 - 2008 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.