X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FFile%2FSpec.pm;h=e1986a96d6b202075819a6e3e0576777a7961d44;hb=b04f6d364dc3b26d2309e24417e692690629b145;hp=616dcbcb7a0d276736c45f3dc1f0a3afb666b72f;hpb=8dcee03ef4ed12141a63dec75da7d736915e7be4;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/File/Spec.pm b/lib/File/Spec.pm index 616dcbc..e1986a9 100644 --- a/lib/File/Spec.pm +++ b/lib/File/Spec.pm @@ -1,49 +1,28 @@ package File::Spec; -require Exporter; - -@ISA = qw(Exporter); -# Items to export into callers namespace by default. Note: do not export -# names by default without a very good reason. Use EXPORT_OK instead. -# Do not simply export all your public functions/methods/constants. -@EXPORT = qw( - -); -@EXPORT_OK = qw($Verbose); - use strict; -use vars qw(@ISA $VERSION $Verbose); - -$VERSION = '0.6'; +use vars qw(@ISA $VERSION); -$Verbose = 0; +$VERSION = '3.05'; +$VERSION = eval $VERSION; -require File::Spec::Unix; +my %module = (MacOS => 'Mac', + MSWin32 => 'Win32', + os2 => 'OS2', + VMS => 'VMS', + epoc => 'Epoc', + NetWare => 'Win32', # Yes, File::Spec::Win32 works on NetWare. + dos => 'OS2', # Yes, File::Spec::OS2 works on DJGPP. + cygwin => 'Cygwin'); -sub load { - my($class,$OS) = @_; - if ($OS eq 'VMS') { - require File::Spec::VMS; - require VMS::Filespec; - 'File::Spec::VMS' - } elsif ($OS eq 'os2') { - require File::Spec::OS2; - 'File::Spec::OS2' - } elsif ($OS eq 'MacOS') { - require File::Spec::Mac; - 'File::Spec::Mac' - } elsif ($OS eq 'MSWin32') { - require File::Spec::Win32; - 'File::Spec::Win32' - } else { - 'File::Spec::Unix' - } -} +my $module = $module{$^O} || 'Unix'; -@ISA = load('File::Spec', $^O); +require "File/Spec/$module.pm"; +@ISA = ("File::Spec::$module"); 1; + __END__ =head1 NAME @@ -52,11 +31,15 @@ File::Spec - portably perform operations on file names =head1 SYNOPSIS -C + use File::Spec; + + $x=File::Spec->catfile('a', 'b', 'c'); + +which returns 'a/b/c' under Unix. Or: -C<$x=File::Spec-Ecatfile('a','b','c');> + use File::Spec::Functions; -which returns 'a/b/c' under Unix. + $x = catfile('a', 'b', 'c'); =head1 DESCRIPTION @@ -78,39 +61,254 @@ OS specific routines is available in a separate module, including: File::Spec::VMS The module appropriate for the current OS is automatically loaded by -File::Spec. Since some modules (like VMS) make use of OS specific -facilities, it may not be possible to load all modules under all operating -systems. +File::Spec. Since some modules (like VMS) make use of facilities available +only under that OS, it may not be possible to load all modules under all +operating systems. -Since File::Spec is object oriented, subroutines should not called directly, +Since File::Spec is object oriented, subroutines should not be called directly, as in: File::Spec::catfile('a','b'); - + but rather as class methods: File::Spec->catfile('a','b'); -For a reference of available functions, please consult L, -which contains the entire set, and inherited by the modules for other -platforms. For further information, please see L, -L, L, or L. +For simple uses, L provides convenient functional +forms of these methods. + +=head1 METHODS + +=over 2 + +=item canonpath + +No physical check on the filesystem, but a logical cleanup of a +path. + + $cpath = File::Spec->canonpath( $path ) ; + +=item catdir + +Concatenate two or more directory names to form a complete path ending +with a directory. But remove the trailing slash from the resulting +string, because it doesn't look good, isn't necessary and confuses +OS/2. Of course, if this is the root directory, don't cut off the +trailing slash :-) + + $path = File::Spec->catdir( @directories ); + +=item catfile + +Concatenate one or more directory names and a filename to form a +complete path ending with a filename + + $path = File::Spec->catfile( @directories, $filename ); + +=item curdir + +Returns a string representation of the current directory. + + $curdir = File::Spec->curdir(); + +=item devnull + +Returns a string representation of the null device. + + $devnull = File::Spec->devnull(); + +=item rootdir + +Returns a string representation of the root directory. + + $rootdir = File::Spec->rootdir(); + +=item tmpdir + +Returns a string representation of the first writable directory from a +list of possible temporary directories. Returns the current directory +if no writable temporary directories are found. The list of directories +checked depends on the platform; e.g. File::Spec::Unix checks C<$ENV{TMPDIR}> +(unless taint is on) and F. + + $tmpdir = File::Spec->tmpdir(); + +=item updir + +Returns a string representation of the parent directory. + + $updir = File::Spec->updir(); + +=item no_upwards + +Given a list of file names, strip out those that refer to a parent +directory. (Does not strip symlinks, only '.', '..', and equivalents.) + + @paths = File::Spec->no_upwards( @paths ); + +=item case_tolerant + +Returns a true or false value indicating, respectively, that alphabetic +case is not or is significant when comparing file specifications. + + $is_case_tolerant = File::Spec->case_tolerant(); + +=item file_name_is_absolute + +Takes as its argument a path, and returns true if it is an absolute path. + + $is_absolute = File::Spec->file_name_is_absolute( $path ); + +This does not consult the local filesystem on Unix, Win32, OS/2, or +Mac OS (Classic). It does consult the working environment for VMS +(see L). + +=item path + +Takes no argument. Returns the environment variable C (or the local +platform's equivalent) as a list. + + @PATH = File::Spec->path(); + +=item join + +join is the same as catfile. + +=item splitpath + +Splits a path in to volume, directory, and filename portions. On systems +with no concept of volume, returns '' for volume. + + ($volume,$directories,$file) = File::Spec->splitpath( $path ); + ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file ); + +For systems with no syntax differentiating filenames from directories, +assumes that the last file is a path unless C<$no_file> is true or a +trailing separator or F or F is present. On Unix, this means that C<$no_file> +true makes this return ( '', $path, '' ). + +The directory portion may or may not be returned with a trailing '/'. + +The results can be passed to L to get back a path equivalent to +(usually identical to) the original path. + +=item splitdir + +The opposite of L. + + @dirs = File::Spec->splitdir( $directories ); + +C<$directories> must be only the directory portion of the path on systems +that have the concept of a volume or that have path syntax that differentiates +files from directories. + +Unlike just splitting the directories on the separator, empty +directory names (C<''>) can be returned, because these are significant +on some OSes. + +=item catpath() + +Takes volume, directory and file portions and returns an entire path. Under +Unix, C<$volume> is ignored, and directory and file are concatenated. A '/' is +inserted if need be. On other OSes, C<$volume> is significant. + + $full_path = File::Spec->catpath( $volume, $directory, $file ); + +=item abs2rel + +Takes a destination path and an optional base path returns a relative path +from the base path to the destination path: + + $rel_path = File::Spec->abs2rel( $path ) ; + $rel_path = File::Spec->abs2rel( $path, $base ) ; + +If C<$base> is not present or '', then L is used. If C<$base> is +relative, then it is converted to absolute form using +L. This means that it is taken to be relative to +L. + +On systems with the concept of volume, if C<$path> and C<$base> appear to be +on two different volumes, we will not attempt to resolve the two +paths, and we will instead simply return C<$path>. Note that previous +versions of this module ignored the volume of C<$base>, which resulted in +garbage results part of the time. + +On systems that have a grammar that indicates filenames, this ignores the +C<$base> filename as well. Otherwise all path components are assumed to be +directories. + +If C<$path> is relative, it is converted to absolute form using L. +This means that it is taken to be relative to L. + +No checks against the filesystem are made. On VMS, there is +interaction with the working environment, as logicals and +macros are expanded. + +Based on code written by Shigio Yamaguchi. + +=item rel2abs() + +Converts a relative path to an absolute path. + + $abs_path = File::Spec->rel2abs( $path ) ; + $abs_path = File::Spec->rel2abs( $path, $base ) ; + +If C<$base> is not present or '', then L is used. If C<$base> is relative, +then it is converted to absolute form using L. This means that it +is taken to be relative to L. + +On systems with the concept of volume, if C<$path> and C<$base> appear to be +on two different volumes, we will not attempt to resolve the two +paths, and we will instead simply return C<$path>. Note that previous +versions of this module ignored the volume of C<$base>, which resulted in +garbage results part of the time. + +On systems that have a grammar that indicates filenames, this ignores the +C<$base> filename as well. Otherwise all path components are assumed to be +directories. + +If C<$path> is absolute, it is cleaned up and returned using L. + +No checks against the filesystem are made. On VMS, there is +interaction with the working environment, as logicals and +macros are expanded. + +Based on code written by Shigio Yamaguchi. + +=back + +For further information, please see L, +L, L, L, or +L. =head1 SEE ALSO -File::Spec::Unix, File::Spec::Mac, File::Spec::OS2, File::Spec::Win32, -File::Spec::VMS, ExtUtils::MakeMaker +L, L, L, +L, L, L, +L -=head1 AUTHORS +=head1 AUTHOR -Kenneth Albanowski >, Andy Dougherty ->, Andreas KEnig ->, Tim Bunce >. VMS -support by Charles Bailey >. OS/2 support by -Ilya Zakharevich >. Mac support by Paul Schinder ->. +Currently maintained by Ken Williams C<< >>. -=cut +The vast majority of the code was written by +Kenneth Albanowski C<< >>, +Andy Dougherty C<< >>, +Andreas KEnig C<< >>, +Tim Bunce C<< >>. +VMS support by Charles Bailey C<< >>. +OS/2 support by Ilya Zakharevich C<< >>. +Mac support by Paul Schinder C<< >>, and +Thomas Wegner C<< >>. +abs2rel() and rel2abs() written by Shigio Yamaguchi C<< >>, +modified by Barrie Slaymaker C<< >>. +splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker. +=head1 COPYRIGHT -1; +Copyright (c) 2004 by the Perl 5 Porters. All rights reserved. + +This program is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut