1NAME
2 HTML::Location - Working with disk to URI file mappings (deprecated: see
3 URI::ToDisk)
4
5STATUS
6 As correctly noted by several users, "HTML::Location" is a really stupid
7 name for this module. I apologise, I was new to the whole CPAN game at
8 the time I first wrote it.
9
10 This module has been relocated to URI::ToDisk. This module will remain
11 indefinately for back-compatibility, but should otherwise be considered
12 deprecated.
13
14 Please convert your code to the otherwise identical URI::ToDisk at your
15 leisure.
16
17SYNOPSIS
18 # We have a directory on disk that is accessible via a web server
19 my $authors = HTML::Location->new( '/var/www/AUTHORS', 'http://ali.as/AUTHORS' );
20
21 # We know where a particular generated file needs to go
22 my $about = $authors->catfile( 'A', 'AD', 'ADAMK', 'about.html' );
23
24 # Save the file to disk
25 my $file = $about->path;
26 open( FILE, ">$file" ) or die "open: $!";
27 print FILE, $content;
28 close FILE;
29
30 # Show the user where to see the file
31 my $uri = $about->uri;
32 print "Author information is at $uri\n";
33
34DESCRIPTION
35 In several process relating to working with the web, we may need to keep
36 track of an area of disk that maps to a particular URL. From this
37 location, we should be able to derived both a filesystem path and URL
38 for any given directory or file under this location that we might need
39 to work with.
40
41 Implementation
42 Internally each "HTML::Location" object contains both a filesystem path,
43 which is altered using File::Spec, and a URI object. When making a
44 change, the path section of the URI is altered using <File::Spec::Unix>.
45
46 Method Calling Conventions
47 The main functional methods, such as "catdir" and "catfile", do not
48 modify the original object, instead returning a new object containing
49 the new location.
50
51 This means that it should be used in a somewhat similar way to
52 File::Spec.
53
54 # The File::Spec way
55 my $path = '/some/path';
56 $path = File::Spec->catfile( $path, 'some', 'file.txt' );
57
58 # The HTML::Location way
59 my $location = HTML::Location->new( '/some/path', 'http://foo.com/blah' );
60 $location = $location->catfile( 'some', 'file.txt' );
61
62 OK, well it's not exactly THAT close, but you get the idea. It also
63 allows you to do method chaining, which is basically
64
65 HTML::Location->new( '/foo', 'http://foo.com/' )->catfile( 'bar.txt' )->uri
66
67 Which may seem a little trivial now, but I expect it to get more useful
68 later. It also means you can do things like this.
69
70 my $base = HTML::Location->new( '/my/cache', 'http://foo.com/' );
71 foreach my $path ( @some_files ) {
72 my $file = $base->catfile( $path );
73 print $file->path . ': ' . $file->uri . "\n";
74 }
75
76 In the above example, you don't have to be continuously cloning the
77 location, because all that stuff happens internally as needed.
78
79METHODS
80 new $path, $http_url
81 The "new" constructor takes as argument a filesystem path and a http(s)
82 URL. Both are required, and the method will return "undef" is either is
83 illegal. The URL is not required to have protocol, host or port
84 sections, and as such allows for host-relative URL to be used.
85
86 Returns a new "HTML::Location" object on success, or "undef" on failure.
87
88 param $various
89 "param" is provided as a mechanism for higher order modules to flexibly
90 accept HTML::Location's as parameters. In this case, it accepts either
91 an existing HTML::Location object, two arguments ($path, $http_url), or
92 a reference to an array containing the same two arguments.
93
94 Returns a HTML::Location if possible, or "undef" if one cannot be
95 provided.
96
97 uri
98 The "uri" method gets and returns the current URI of the location, in
99 string form.
100
101 URI
102 The capitalised "URI" method gets and returns a copy of the raw URI,
103 held internally by the location. Note that only a copy is returned, and
104 as such as safe to further modify yourself without effecting the
105 location.
106
107 path
108 The "path" method returns the filesystem path componant of the location.
109
110 catdir 'dir', 'dir', ...
111 A File::Spec workalike, the "catdir" method acts in the same way as for
112 File::Spec, modifying both componants of the location. The "catdir"
113 method returns a new HTML::Location object representing the new
114 location, or "undef" on error.
115
116 catfile [ 'dir', ..., ] $file
117 Like "catdir", the "catfile" method acts in the same was as for
118 File::Spec, and returns a new HTML::Location object representing the
119 file, or "undef" on error.
120
121TO DO
122 Add more File::Spec-y methods as needed. Ask if you need one.
123
124SUPPORT
125 Bugs should be reported via the CPAN bug tracker at
126
127 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-Location>
128
129 For other issues, or commercial enhancement or support, contact the
130 author.
131
132AUTHOR
133 Adam Kennedy <adamk@cpan.org>
134
135COPYRIGHT
136 Copyright 2003 - 2008 Adam Kennedy.
137
138 This program is free software; you can redistribute it and/or modify it
139 under the same terms as Perl itself.
140
141 The full text of the license can be found in the LICENSE file included
142 with this module.
143
144