7 @ISA = qw(URI::_generic);
9 # Map from $^O values to implementation classes. The Unix
10 # class is the default.
24 my($OS) = shift || $^O;
26 my $class = "URI::file::" . ($os_class{$OS} || "Unix");
28 unless (%{"$class\::"}) {
29 eval "require $class";
35 sub path { shift->path_query(@_) }
36 sub host { shift->authority(@_) }
40 my($class, $path, $os) = @_;
41 os_class($os)->new($path);
47 my $file = $class->new(shift);
48 return $file->abs($class->cwd) unless $$file =~ /^file:/;
57 $cwd = VMS::Filespec::unixpath($cwd) if $^O eq 'VMS';
58 $cwd = $class->new($cwd);
59 $cwd .= "/" unless substr($cwd, -1, 1) eq "/";
66 os_class($os)->file($self);
72 os_class($os)->dir($self);
81 URI::file - URI that map to local file names
87 $u1 = URI->new("file:/foo/bar");
88 $u2 = URI->new("foo/bar", "file");
90 $u3 = URI::file->new($path);
91 $u4 = URI::file->new("c:\\windows\\", "win32");
98 The C<URI::file> class supports C<URI> objects belonging to the I<file>
99 URI scheme. This scheme allows us to map the conventional file names
100 found on various computer systems to the URI name space. An old
101 specification of the I<file> URI scheme is found in RFC 1738. Some
102 older background information is also in RFC 1630. There are no newer
103 specifications as far as I know.
105 If you want simply to construct I<file> URI objects from URI strings,
106 use the normal C<URI> constructor. If you want to construct I<file>
107 URI objects from the actual file names used by various systems, then
108 use one of the following C<URI::file> constructors:
112 =item $u = URI::file->new( $filename, [$os] )
114 Maps a file name to the I<file:> URI name space, creates an URI object
115 and returns it. The $filename is interpreted as one belonging to the
116 indicated operating system ($os), which defaults to the value of the
117 $^O variable. The $filename can be either absolute or relative, and
118 the corresponding type of URI object for $os is returned.
120 =item $u = URI::file->new_abs( $filename, [$os] )
122 Same as URI::file->new, but will make sure that the URI returned
123 represents an absolute file name. If the $filename argument is
124 relative, then the name is resolved relative to the current directory,
125 i.e. this constructor is really the same as:
127 URI::file->new($filename)->abs(URI::file->cwd);
129 =item $u = URI::file->cwd
131 Returns a I<file> URI that represents the current working directory.
136 The following methods are supported for I<file> URI (in addition to
137 the common and generic methods described in L<URI>):
141 =item $u->file( [$os] )
143 This method return a file name. It maps from the URI name space
144 to the file name space of the indicated operating system.
146 It might return C<undef> if the name can not be represented in the
147 indicated file system.
149 =item $u->dir( [$os] )
151 Some systems use a different form for names of directories than for plain
152 files. Use this method if you know you want to use the name for
157 The C<URI::file> module can be used to map generic file names to names
158 suitable for the current system. As such, it can work as a nice
159 replacement for the C<File::Spec> module. For instance the following
160 code will translate the Unix style file name F<Foo/Bar.pm> to a name
161 suitable for the local system.
163 $file = URI::file->new("Foo/Bar.pm", "unix")->file;
164 die "Can't map filename Foo/Bar.pm for $^O" unless defined $file;
165 open(FILE, $file) || die "Can't open '$file': $!";
166 # do something with FILE
170 Most computer systems today have hierarchically organized file systems.
171 Mapping the names used in these systems to the generic URI syntax
172 allows us to work with relative file URIs that behave as they should
173 when resolved using the generic algorithm for URIs (specified in RFC
174 2396). Mapping a file name to the generic URI syntax involves mapping
175 the path separator character to "/" and encoding of any reserved
176 characters that appear in the path segments of the file names. If
177 path segments consisting of the strings "." or ".." have a
178 different meaning than what is specified for generic URIs, then these
179 must be encoded as well.
181 If the file system has device, volume or drive specifications as
182 the root of the name space, then it makes sense to map them to the
183 authority field of the generic URI syntax. This makes sure that
184 relative URI can not be resolved "above" them , i.e. generally how
185 relative file names work in those systems.
187 Another common use of the authority field is to encode the host that
188 this file name is valid on. The host name "localhost" is special and
189 generally have the same meaning as an missing or empty authority
190 field. This use will be in conflict with using it as a device
191 specification, but can often be resolved for device specifications
192 having characters not legal in plain host names.
194 File name to URI mapping in normally not one-to-one. There are
195 usually many URI that map to the same file name. For instance an
196 authority of "localhost" maps the same as a URI with a missing or empty
199 Example 1: The Mac use ":" as path separator, but not in the same way
200 as generic URI. ":foo" is a relative name. "foo:bar" is an absolute
201 name. Also path segments can contain the "/" character as well as be
202 literal "." or "..". It means that we will map like this:
205 ---------- -------------------
206 :foo:bar <==> foo/bar
208 ::foo:bar <==> ../foo/bar
210 foo:bar <==> file:/foo/bar
211 foo:bar: <==> file:/foo/bar/
214 foo/ <== file:/foo%2F
215 ./foo.txt <== file:/.%2Ffoo.txt
217 Note that if you want a relative URL, you *must* begin the path with a :. Any
218 path that begins with [^:] will be treated as absolute.
220 Example 2: The Unix file system is easy to map as it use the same path
221 separator as URIs, have a single root, and segments of "." and ".."
222 have the same meaning. URIs that have the character "\0" or "/" as
223 part of any path segment can not be turned into valid Unix file names.
226 ---------- ------------------
228 /foo/bar <==> file:/foo/bar
229 /foo/bar <== file://localhost/foo/bar
231 <undef> <== file:/fo%00/bar
241 There is clearly a danger of confusion that a link made to a local
242 file should be followed by someone on a different system, with
243 unexpected and possibly harmful results. Therefore, the convention
244 is that even a "file" URL is provided with a host part. This allows
245 a client on another system to know that it cannot access the file
246 system, or perhaps to use some other local mechanism to access the
249 The special value "localhost" is used in the host field to indicate
250 that the filename should really be used on whatever host one is.
251 This for example allows links to be made to files which are
252 distribted on many machines, or to "your unix local password file"
253 subject of course to consistency across the users of the data.
255 A void host field is equivalent to "localhost".
259 L<URI>, L<File::Spec>, L<perlport>
263 Copyright 1995-1998 Gisle Aas.
265 This library is free software; you can redistribute it and/or
266 modify it under the same terms as Perl itself.