view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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/' );