1URI::file(3)          User Contributed Perl Documentation         URI::file(3)
2
3
4

NAME

6       URI::file - URI that maps to local file names
7

SYNOPSIS

9        use URI::file;
10
11        $u1 = URI->new("file:/foo/bar");
12        $u2 = URI->new("foo/bar", "file");
13
14        $u3 = URI::file->new($path);
15        $u4 = URI::file->new("c:\\windows\\", "win32");
16
17        $u1->file;
18        $u1->file("mac");
19

DESCRIPTION

21       The "URI::file" class supports "URI" objects belonging to the file URI
22       scheme.  This scheme allows us to map the conventional file names found
23       on various computer systems to the URI name space, see RFC 8089
24       <https://www.rfc-editor.org/rfc/rfc8089.html>.
25
26       If you simply want to construct file URI objects from URI strings, use
27       the normal "URI" constructor.  If you want to construct file URI
28       objects from the actual file names used by various systems, then use
29       one of the following "URI::file" constructors:
30
31       $u = URI::file->new( $filename, [$os] )
32           Maps a file name to the file: URI name space, creates a URI object
33           and returns it.  The $filename is interpreted as belonging to the
34           indicated operating system ($os), which defaults to the value of
35           the $^O variable.  The $filename can be either absolute or
36           relative, and the corresponding type of URI object for $os is
37           returned.
38
39       $u = URI::file->new_abs( $filename, [$os] )
40           Same as URI::file->new, but makes sure that the URI returned
41           represents an absolute file name.  If the $filename argument is
42           relative, then the name is resolved relative to the current
43           directory, i.e. this constructor is really the same as:
44
45             URI::file->new($filename)->abs(URI::file->cwd);
46
47       $u = URI::file->cwd
48           Returns a file URI that represents the current working directory.
49           See Cwd.
50
51       The following methods are supported for file URI (in addition to the
52       common and generic methods described in URI):
53
54       $u->file( [$os] )
55           Returns a file name.  It maps from the URI name space to the file
56           name space of the indicated operating system.
57
58           It might return "undef" if the name can not be represented in the
59           indicated file system.
60
61       $u->dir( [$os] )
62           Some systems use a different form for names of directories than for
63           plain files.  Use this method if you know you want to use the name
64           for a directory.
65
66       The "URI::file" module can be used to map generic file names to names
67       suitable for the current system.  As such, it can work as a nice
68       replacement for the "File::Spec" module.  For instance, the following
69       code translates the UNIX-style file name Foo/Bar.pm to a name suitable
70       for the local system:
71
72         $file = URI::file->new("Foo/Bar.pm", "unix")->file;
73         die "Can't map filename Foo/Bar.pm for $^O" unless defined $file;
74         open(FILE, $file) || die "Can't open '$file': $!";
75         # do something with FILE
76

MAPPING NOTES

78       Most computer systems today have hierarchically organized file systems.
79       Mapping the names used in these systems to the generic URI syntax
80       allows us to work with relative file URIs that behave as they should
81       when resolved using the generic algorithm for URIs (specified in RFC
82       3986 <https://www.rfc-editor.org/rfc/rfc3986.html>).  Mapping a file
83       name to the generic URI syntax involves mapping the path separator
84       character to "/" and encoding any reserved characters that appear in
85       the path segments of the file name.  If path segments consisting of the
86       strings "." or ".." have a different meaning than what is specified for
87       generic URIs, then these must be encoded as well.
88
89       If the file system has device, volume or drive specifications as the
90       root of the name space, then it makes sense to map them to the
91       authority field of the generic URI syntax.  This makes sure that
92       relative URIs can not be resolved "above" them, i.e. generally how
93       relative file names work in those systems.
94
95       Another common use of the authority field is to encode the host on
96       which this file name is valid.  The host name "localhost" is special
97       and generally has the same meaning as a missing or empty authority
98       field.  This use is in conflict with using it as a device
99       specification, but can often be resolved for device specifications
100       having characters not legal in plain host names.
101
102       File name to URI mapping in normally not one-to-one.  There are usually
103       many URIs that map to any given file name.  For instance, an authority
104       of "localhost" maps the same as a URI with a missing or empty
105       authority.
106
107       Example 1: The Mac classic (Mac OS 9 and earlier) used ":" as path
108       separator, but not in the same way as a generic URI. ":foo" was a
109       relative name.  "foo:bar" was an absolute name.  Also, path segments
110       could contain the "/" character as well as the literal "." or "..".  So
111       the mapping looks like this:
112
113         Mac classic           URI
114         ----------            -------------------
115         :foo:bar     <==>     foo/bar
116         :            <==>     ./
117         ::foo:bar    <==>     ../foo/bar
118         :::          <==>     ../../
119         foo:bar      <==>     file:/foo/bar
120         foo:bar:     <==>     file:/foo/bar/
121         ..           <==>     %2E%2E
122         <undef>      <==      /
123         foo/         <==      file:/foo%2F
124         ./foo.txt    <==      file:/.%2Ffoo.txt
125
126       Note that if you want a relative URL, you *must* begin the path with a
127       :.  Any path that begins with [^:] is treated as absolute.
128
129       Example 2: The UNIX file system is easy to map, as it uses the same
130       path separator as URIs, has a single root, and segments of "." and ".."
131       have the same meaning.  URIs that have the character "\0" or "/" as
132       part of any path segment can not be turned into valid UNIX file names.
133
134         UNIX                  URI
135         ----------            ------------------
136         foo/bar      <==>     foo/bar
137         /foo/bar     <==>     file:/foo/bar
138         /foo/bar     <==      file://localhost/foo/bar
139         file:         ==>     ./file:
140         <undef>      <==      file:/fo%00/bar
141         /            <==>     file:/
142

CONFIGURATION VARIABLES

144       The following configuration variables influence how the class and its
145       methods behave:
146
147       %URI::file::OS_CLASS
148           This hash maps OS identifiers to implementation classes.  You might
149           want to add or modify this if you want to plug in your own file
150           handler class.  Normally the keys should match the $^O values in
151           use.
152
153           If there is no mapping then the "Unix" implementation is used.
154
155       $URI::file::DEFAULT_AUTHORITY
156           This determines what "authority" string to include in absolute file
157           URIs.  It defaults to "".  If you prefer verbose URIs you might set
158           it to be "localhost".
159
160           Setting this value to "undef" forces behaviour compatible to URI
161           v1.31 and earlier.  In this mode host names in UNC paths and drive
162           letters are mapped to the authority component on Windows, while we
163           produce authority-less URIs on Unix.
164

SEE ALSO

166       URI, File::Spec, perlport
167
169       Copyright 1995-1998,2004 Gisle Aas.
170
171       This library is free software; you can redistribute it and/or modify it
172       under the same terms as Perl itself.
173
174
175
176perl v5.36.0                      2022-11-03                      URI::file(3)
Impressum