home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _af8eb328ac3302319cf0fc5254d9c89a < prev    next >
Text File  |  2004-06-01  |  9KB  |  272 lines
  1. package URI::file;
  2.  
  3. use strict;
  4. use vars qw(@ISA $VERSION);
  5.  
  6. require URI::_generic;
  7. @ISA = qw(URI::_generic);
  8. $VERSION = sprintf("%d.%02d", q$Revision: 4.14 $ =~ /(\d+)\.(\d+)/);
  9.  
  10. use URI::Escape qw(uri_unescape);
  11.  
  12. # Map from $^O values to implementation classes.  The Unix
  13. # class is the default.
  14. my %os_class = (
  15.      os2     => "OS2",
  16.      mac     => "Mac",
  17.      MacOS   => "Mac",
  18.      MSWin32 => "Win32",
  19.      win32   => "Win32",
  20.      msdos   => "FAT",
  21.      dos     => "FAT",
  22.      qnx     => "QNX",
  23. );
  24.  
  25. sub os_class
  26. {
  27.     my($OS) = shift || $^O;
  28.  
  29.     my $class = "URI::file::" . ($os_class{$OS} || "Unix");
  30.     no strict 'refs';
  31.     unless (%{"$class\::"}) {
  32.     eval "require $class";
  33.     die $@ if $@;
  34.     }
  35.     $class;
  36. }
  37.  
  38. sub path { shift->path_query(@_) }
  39. sub host { uri_unescape(shift->authority(@_)) }
  40.  
  41. sub new
  42. {
  43.     my($class, $path, $os) = @_;
  44.     os_class($os)->new($path);
  45. }
  46.  
  47. sub new_abs
  48. {
  49.     my $class = shift;
  50.     my $file = $class->new(shift);
  51.     return $file->abs($class->cwd) unless $$file =~ /^file:/;
  52.     $file;
  53. }
  54.  
  55. sub cwd
  56. {
  57.     my $class = shift;
  58.     require Cwd;
  59.     my $cwd = Cwd::cwd();
  60.     $cwd = VMS::Filespec::unixpath($cwd) if $^O eq 'VMS';
  61.     $cwd = $class->new($cwd);
  62.     $cwd .= "/" unless substr($cwd, -1, 1) eq "/";
  63.     $cwd;
  64. }
  65.  
  66. sub file
  67. {
  68.     my($self, $os) = @_;
  69.     os_class($os)->file($self);
  70. }
  71.  
  72. sub dir
  73. {
  74.     my($self, $os) = @_;
  75.     os_class($os)->dir($self);
  76. }
  77.  
  78. 1;
  79.  
  80. __END__
  81.  
  82. =head1 NAME
  83.  
  84. URI::file - URI that maps to local file names
  85.  
  86. =head1 SYNOPSIS
  87.  
  88.  use URI::file;
  89.  
  90.  $u1 = URI->new("file:/foo/bar");
  91.  $u2 = URI->new("foo/bar", "file");
  92.  
  93.  $u3 = URI::file->new($path);
  94.  $u4 = URI::file->new("c:\\windows\\", "win32");
  95.  
  96.  $u1->file;
  97.  $u1->file("mac");
  98.  
  99. =head1 DESCRIPTION
  100.  
  101. The C<URI::file> class supports C<URI> objects belonging to the I<file>
  102. URI scheme.  This scheme allows us to map the conventional file names
  103. found on various computer systems to the URI name space.  An old
  104. specification of the I<file> URI scheme is found in RFC 1738.  Some
  105. older background information is also in RFC 1630. There are no newer
  106. specifications as far as I know.
  107.  
  108. If you simply want to construct I<file> URI objects from URI strings,
  109. use the normal C<URI> constructor.  If you want to construct I<file>
  110. URI objects from the actual file names used by various systems, then
  111. use one of the following C<URI::file> constructors:
  112.  
  113. =over 4
  114.  
  115. =item $u = URI::file->new( $filename, [$os] )
  116.  
  117. Maps a file name to the I<file:> URI name space, creates a URI object
  118. and returns it.  The $filename is interpreted as belonging to the
  119. indicated operating system ($os), which defaults to the value of the
  120. $^O variable.  The $filename can be either absolute or relative, and
  121. the corresponding type of URI object for $os is returned.
  122.  
  123. =item $u = URI::file->new_abs( $filename, [$os] )
  124.  
  125. Same as URI::file->new, but makes sure that the URI returned
  126. represents an absolute file name.  If the $filename argument is
  127. relative, then the name is resolved relative to the current directory,
  128. i.e. this constructor is really the same as:
  129.  
  130.   URI::file->new($filename)->abs(URI::file->cwd);
  131.  
  132. =item $u = URI::file->cwd
  133.  
  134. Returns a I<file> URI that represents the current working directory.
  135. See L<Cwd>.
  136.  
  137. =back
  138.  
  139. The following methods are supported for I<file> URI (in addition to
  140. the common and generic methods described in L<URI>):
  141.  
  142. =over 4
  143.  
  144. =item $u->file( [$os] )
  145.  
  146. Returns a file name.  It maps from the URI name space
  147. to the file name space of the indicated operating system.
  148.  
  149. It might return C<undef> if the name can not be represented in the
  150. indicated file system.
  151.  
  152. =item $u->dir( [$os] )
  153.  
  154. Some systems use a different form for names of directories than for plain
  155. files.  Use this method if you know you want to use the name for
  156. a directory.
  157.  
  158. =back
  159.  
  160. The C<URI::file> module can be used to map generic file names to names
  161. suitable for the current system.  As such, it can work as a nice
  162. replacement for the C<File::Spec> module.  For instance, the following
  163. code translates the UNIX-style file name F<Foo/Bar.pm> to a name
  164. suitable for the local system:
  165.  
  166.   $file = URI::file->new("Foo/Bar.pm", "unix")->file;
  167.   die "Can't map filename Foo/Bar.pm for $^O" unless defined $file;
  168.   open(FILE, $file) || die "Can't open '$file': $!";
  169.   # do something with FILE
  170.  
  171. =head1 MAPPING NOTES
  172.  
  173. Most computer systems today have hierarchically organized file systems.
  174. Mapping the names used in these systems to the generic URI syntax
  175. allows us to work with relative file URIs that behave as they should
  176. when resolved using the generic algorithm for URIs (specified in RFC
  177. 2396).  Mapping a file name to the generic URI syntax involves mapping
  178. the path separator character to "/" and encoding any reserved
  179. characters that appear in the path segments of the file name.  If
  180. path segments consisting of the strings "." or ".." have a
  181. different meaning than what is specified for generic URIs, then these
  182. must be encoded as well.
  183.  
  184. If the file system has device, volume or drive specifications as
  185. the root of the name space, then it makes sense to map them to the
  186. authority field of the generic URI syntax.  This makes sure that
  187. relative URIs can not be resolved "above" them, i.e. generally how
  188. relative file names work in those systems.
  189.  
  190. Another common use of the authority field is to encode the host on which
  191. this file name is valid.  The host name "localhost" is special and
  192. generally has the same meaning as a missing or empty authority
  193. field.  This use is in conflict with using it as a device
  194. specification, but can often be resolved for device specifications
  195. having characters not legal in plain host names.
  196.  
  197. File name to URI mapping in normally not one-to-one.  There are
  198. usually many URIs that map to any given file name.  For instance, an
  199. authority of "localhost" maps the same as a URI with a missing or empty
  200. authority.
  201.  
  202. Example 1: The Mac uses ":" as path separator, but not in the same way
  203. as a generic URI. ":foo" is a relative name.  "foo:bar" is an absolute
  204. name.  Also, path segments can contain the "/" character as well as the
  205. literal "." or "..".  So the mapping looks like this:
  206.  
  207.   Mac                   URI
  208.   ----------            -------------------
  209.   :foo:bar     <==>     foo/bar
  210.   :            <==>     ./
  211.   ::foo:bar    <==>     ../foo/bar
  212.   :::          <==>     ../../
  213.   foo:bar      <==>     file:/foo/bar
  214.   foo:bar:     <==>     file:/foo/bar/
  215.   ..           <==>     %2E%2E
  216.   <undef>      <==      /
  217.   foo/         <==      file:/foo%2F
  218.   ./foo.txt    <==      file:/.%2Ffoo.txt
  219.  
  220. Note that if you want a relative URL, you *must* begin the path with a :.  Any
  221. path that begins with [^:] is treated as absolute.
  222.  
  223. Example 2: The UNIX file system is easy to map, as it uses the same path
  224. separator as URIs, has a single root, and segments of "." and ".."
  225. have the same meaning.  URIs that have the character "\0" or "/" as
  226. part of any path segment can not be turned into valid UNIX file names.
  227.  
  228.   UNIX                  URI
  229.   ----------            ------------------
  230.   foo/bar      <==>     foo/bar
  231.   /foo/bar     <==>     file:/foo/bar
  232.   /foo/bar     <==      file://localhost/foo/bar
  233.   file:         ==>     ./file:
  234.   <undef>      <==      file:/fo%00/bar
  235.   /            <==>     file:/
  236.  
  237. =cut
  238.  
  239.  
  240. RFC 1630
  241.  
  242.    [...]
  243.  
  244.    There is clearly a danger of confusion that a link made to a local
  245.    file should be followed by someone on a different system, with
  246.    unexpected and possibly harmful results.  Therefore, the convention
  247.    is that even a "file" URL is provided with a host part.  This allows
  248.    a client on another system to know that it cannot access the file
  249.    system, or perhaps to use some other local mechanism to access the
  250.    file.
  251.  
  252.    The special value "localhost" is used in the host field to indicate
  253.    that the filename should really be used on whatever host one is.
  254.    This for example allows links to be made to files which are
  255.    distribted on many machines, or to "your unix local password file"
  256.    subject of course to consistency across the users of the data.
  257.  
  258.    A void host field is equivalent to "localhost".
  259.  
  260. =head1 SEE ALSO
  261.  
  262. L<URI>, L<File::Spec>, L<perlport>
  263.  
  264. =head1 COPYRIGHT
  265.  
  266. Copyright 1995-1998 Gisle Aas.
  267.  
  268. This library is free software; you can redistribute it and/or
  269. modify it under the same terms as Perl itself.
  270.  
  271. =cut
  272.