312 lines
9.2 KiB
HTML
312 lines
9.2 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of URI::file</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>URI::file</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2020-02-08<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
URI::file - URI that maps to local file names
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use URI::file;
|
|
|
|
$u1 = URI->new("file:/foo/bar");
|
|
$u2 = URI->new("foo/bar", "file");
|
|
|
|
$u3 = URI::file->new($path);
|
|
$u4 = URI::file->new("c:\\windows\\", "win32");
|
|
|
|
$u1->file;
|
|
$u1->file("mac");
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <TT>"URI::file"</TT> class supports <TT>"URI"</TT> objects belonging to the <I>file</I>
|
|
<FONT SIZE="-1">URI</FONT> scheme. This scheme allows us to map the conventional file names
|
|
found on various computer systems to the <FONT SIZE="-1">URI</FONT> name space. An old
|
|
specification of the <I>file</I> <FONT SIZE="-1">URI</FONT> scheme is found in <FONT SIZE="-1">RFC 1738.</FONT> Some
|
|
older background information is also in <FONT SIZE="-1">RFC 1630.</FONT> There are no newer
|
|
specifications as far as I know.
|
|
<P>
|
|
|
|
If you simply want to construct <I>file</I> <FONT SIZE="-1">URI</FONT> objects from <FONT SIZE="-1">URI</FONT> strings,
|
|
use the normal <TT>"URI"</TT> constructor. If you want to construct <I>file</I>
|
|
<FONT SIZE="-1">URI</FONT> objects from the actual file names used by various systems, then
|
|
use one of the following <TT>"URI::file"</TT> constructors:
|
|
<DL COMPACT>
|
|
<DT id="1">$u = URI::file->new( $filename, [$os] )<DD>
|
|
|
|
|
|
|
|
|
|
Maps a file name to the <I>file:</I> <FONT SIZE="-1">URI</FONT> name space, creates a <FONT SIZE="-1">URI</FONT> object
|
|
and returns it. The <TT>$filename</TT> is interpreted as belonging to the
|
|
indicated operating system ($os), which defaults to the value of the
|
|
$^O variable. The <TT>$filename</TT> can be either absolute or relative, and
|
|
the corresponding type of <FONT SIZE="-1">URI</FONT> object for <TT>$os</TT> is returned.
|
|
<DT id="2">$u = URI::file->new_abs( $filename, [$os] )<DD>
|
|
|
|
|
|
|
|
|
|
Same as URI::file->new, but makes sure that the <FONT SIZE="-1">URI</FONT> returned
|
|
represents an absolute file name. If the <TT>$filename</TT> argument is
|
|
relative, then the name is resolved relative to the current directory,
|
|
i.e. this constructor is really the same as:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
URI::file->new($filename)->abs(URI::file->cwd);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="3">$u = URI::file->cwd<DD>
|
|
|
|
|
|
|
|
|
|
Returns a <I>file</I> <FONT SIZE="-1">URI</FONT> that represents the current working directory.
|
|
See Cwd.
|
|
</DL>
|
|
<P>
|
|
|
|
The following methods are supported for <I>file</I> <FONT SIZE="-1">URI</FONT> (in addition to
|
|
the common and generic methods described in <FONT SIZE="-1">URI</FONT>):
|
|
<DL COMPACT>
|
|
<DT id="4">$u->file( [$os] )<DD>
|
|
|
|
|
|
|
|
|
|
Returns a file name. It maps from the <FONT SIZE="-1">URI</FONT> name space
|
|
to the file name space of the indicated operating system.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It might return <TT>"undef"</TT> if the name can not be represented in the
|
|
indicated file system.
|
|
<DT id="5">$u->dir( [$os] )<DD>
|
|
|
|
|
|
|
|
|
|
Some systems use a different form for names of directories than for plain
|
|
files. Use this method if you know you want to use the name for
|
|
a directory.
|
|
</DL>
|
|
<P>
|
|
|
|
The <TT>"URI::file"</TT> module can be used to map generic file names to names
|
|
suitable for the current system. As such, it can work as a nice
|
|
replacement for the <TT>"File::Spec"</TT> module. For instance, the following
|
|
code translates the UNIX-style file name <I>Foo/Bar.pm</I> to a name
|
|
suitable for the local system:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
$file = URI::file->new("Foo/Bar.pm", "unix")->file;
|
|
die "Can't map filename Foo/Bar.pm for $^O" unless defined $file;
|
|
open(FILE, $file) || die "Can't open '$file': $!";
|
|
# do something with FILE
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>MAPPING NOTES</H2>
|
|
|
|
|
|
|
|
Most computer systems today have hierarchically organized file systems.
|
|
Mapping the names used in these systems to the generic <FONT SIZE="-1">URI</FONT> syntax
|
|
allows us to work with relative file URIs that behave as they should
|
|
when resolved using the generic algorithm for URIs (specified in <FONT SIZE="-1">RFC
|
|
2396</FONT>). Mapping a file name to the generic <FONT SIZE="-1">URI</FONT> syntax involves mapping
|
|
the path separator character to ``/'' and encoding any reserved
|
|
characters that appear in the path segments of the file name. If
|
|
path segments consisting of the strings ``.'' or ``..'' have a
|
|
different meaning than what is specified for generic URIs, then these
|
|
must be encoded as well.
|
|
<P>
|
|
|
|
If the file system has device, volume or drive specifications as
|
|
the root of the name space, then it makes sense to map them to the
|
|
authority field of the generic <FONT SIZE="-1">URI</FONT> syntax. This makes sure that
|
|
relative URIs can not be resolved ``above'' them, i.e. generally how
|
|
relative file names work in those systems.
|
|
<P>
|
|
|
|
Another common use of the authority field is to encode the host on which
|
|
this file name is valid. The host name ``localhost'' is special and
|
|
generally has the same meaning as a missing or empty authority
|
|
field. This use is in conflict with using it as a device
|
|
specification, but can often be resolved for device specifications
|
|
having characters not legal in plain host names.
|
|
<P>
|
|
|
|
File name to <FONT SIZE="-1">URI</FONT> mapping in normally not one-to-one. There are
|
|
usually many URIs that map to any given file name. For instance, an
|
|
authority of ``localhost'' maps the same as a <FONT SIZE="-1">URI</FONT> with a missing or empty
|
|
authority.
|
|
<P>
|
|
|
|
Example 1: The Mac classic (Mac <FONT SIZE="-1">OS 9</FONT> and earlier) used ``:'' as path separator,
|
|
but not in the same way as a generic <FONT SIZE="-1">URI.</FONT> ``:foo'' was a relative name. ``foo:bar''
|
|
was an absolute name. Also, path segments could contain the ``/'' character as well
|
|
as the literal ``.'' or ``..''. So the mapping looks like this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
Mac classic URI
|
|
---------- -------------------
|
|
:foo:bar <==> foo/bar
|
|
: <==> ./
|
|
::foo:bar <==> ../foo/bar
|
|
::: <==> ../../
|
|
foo:bar <==> file:/foo/bar
|
|
foo:bar: <==> file:/foo/bar/
|
|
.. <==> %2E%2E
|
|
<undef> <== /
|
|
foo/ <== file:/foo%2F
|
|
./foo.txt <== file:/.%2Ffoo.txt
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Note that if you want a relative <FONT SIZE="-1">URL,</FONT> you *must* begin the path with a :. Any
|
|
path that begins with [^:] is treated as absolute.
|
|
<P>
|
|
|
|
Example 2: The <FONT SIZE="-1">UNIX</FONT> file system is easy to map, as it uses the same path
|
|
separator as URIs, has a single root, and segments of ``.'' and ``..''
|
|
have the same meaning. URIs that have the character ``\0'' or ``/'' as
|
|
part of any path segment can not be turned into valid <FONT SIZE="-1">UNIX</FONT> file names.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
UNIX URI
|
|
---------- ------------------
|
|
foo/bar <==> foo/bar
|
|
/foo/bar <==> file:/foo/bar
|
|
/foo/bar <== <A HREF="file://localhost/foo/bar">file://localhost/foo/bar</A>
|
|
file: ==> ./file:
|
|
<undef> <== file:/fo%00/bar
|
|
/ <==> file:/
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H2>CONFIGURATION VARIABLES</H2>
|
|
|
|
|
|
|
|
The following configuration variables influence how the class and its
|
|
methods behave:
|
|
<DL COMPACT>
|
|
<DT id="6">%URI::file::OS_CLASS<DD>
|
|
|
|
|
|
|
|
|
|
This hash maps <FONT SIZE="-1">OS</FONT> identifiers to implementation classes. You might
|
|
want to add or modify this if you want to plug in your own file
|
|
handler class. Normally the keys should match the $^O values in use.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If there is no mapping then the ``Unix'' implementation is used.
|
|
<DT id="7">$URI::file::DEFAULT_AUTHORITY<DD>
|
|
|
|
|
|
|
|
|
|
This determine what ``authority'' string to include in absolute file
|
|
URIs. It defaults to "``. If you prefer verbose URIs you might set it
|
|
to be ''localhost".
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Setting this value to <TT>"undef"</TT> force behaviour compatible to <FONT SIZE="-1">URI</FONT> v1.31
|
|
and earlier. In this mode host names in <FONT SIZE="-1">UNC</FONT> paths and drive letters
|
|
are mapped to the authority component on Windows, while we produce
|
|
authority-less URIs on Unix.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<FONT SIZE="-1">URI</FONT>, File::Spec, perlport
|
|
<A NAME="lbAH"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright 1995-1998,2004 Gisle Aas.
|
|
<P>
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="8"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="9"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="10"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="11"><A HREF="#lbAE">MAPPING NOTES</A><DD>
|
|
<DT id="12"><A HREF="#lbAF">CONFIGURATION VARIABLES</A><DD>
|
|
<DT id="13"><A HREF="#lbAG">SEE ALSO</A><DD>
|
|
<DT id="14"><A HREF="#lbAH">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:59 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|