File::PathConvert 0.83 for perl version5 or later


Copyright (c) 1998 Barrie Slaymaker. All rights reserved.
Copyright (c) 1996, 1997, 1998 Shigio Yamaguchi. All rights reserved.
This program is open source software; you can redistribute it and/or
modify it under the same terms as Perl itself.



** Introduction **

This module provides multiplatform routines to convert paths and URLs from 
absolute to relative and vice versa and to split paths into volume, 
directory, and filename portions.

The path splitting and joining are useful for non-fully hierarchical
pathnames like URLs, Mac, VMS, DOS/Win32, and OS/2, for instance.

These routines are still under development and need extensive testing, most
especially for URLs, Mac, and VMS.

See the POD for more information.

Please send your comments and patches to rbs@telerama.com



** Installation **

You need perl version 5.002 or later.

   perl Makefile.PL
   make
   make test
   make install


** TODO **

    This cleanup of m@name/..(/|$)@ 
    needs to be improved by making it clean up m@name/../@
    or m@(.)/name/..$@ or m@($isrootRE)name/..$@, preserving the
    leading root indicator. The current approach will end up
    leaving trailing slashes: /a/b/.. becomes /a/, not /a.

    Add option to regularize() to force '\' or '/' on Win32 (or
    just leave them be). Currently, the Win32 setting uses '/' by default
    because there are lots of perl scripts out there that are unixian
    in nature that need to run under Win32. But, there are some applications
    of perl under Win32 that 

    (Possibly) add an option to speed things up by using abs_path()
    instead of cwd().

    (Possibly) alter realpath() to use abs_path() for speed.

    MacOS and VMS beta testing: there have to be some bugs in
    there.


** Revision History **

All revisions up to 0.4 by Shigio Yamaguchi.  0.4 to present by Barrie
Slaymaker.  Thanks Shigio!

17-Sep-1996  first RFC on comp.lang.perl.modules.
      Subject: RFC File::PathConvert module
      Message-ID: <51m90o$pos@newsgate.so-net.or.jp>


07-Oct-1996  second RFC on comp.lang.perl.modules.
      Subject: 2nd RFC File::PathConvert module
      Message-ID: <53a449$2qo@newsgate.so-net.or.jp>

      PathConvert.pm -
         use @EXPORT_OK instead of @EXPORT.
         realpath added.
         use $SL variable for path separator.


0.1   23-Oct-1996
         Tested with perl5.003_02.


0.2   3-Sep-1998

      PathConvert.pm
         - SYNOPSIS fixed.
         - Tested with perl5.004_02.
      README   
         - Mail address changed.
         - History added.


0.3   9-Jan-1998

      PathConvert.pm
         - fixed the statment of online manual.

      Following useful modifications were submitted by Jesse N. Glick.

      * using $VERSION, to placate CPAN, Exporter, MakeMaker, etc.
      * exporting package variables, all of which seem to be designed
        for possible customization (or retrieval of info in the case
        of $resolved)
      * prototyping public functions (those extra semicolons prevent
        e.g. CPerl mode from thinking `$' escapes the following `)'
        and messing up Emacs)
      * using standard indented format for literal program examples;
        use of .br is nonstandard and will not work on anything but
        nroff/troff (e.g. pod2html)
      * including suggested use of $resolved in SYNOPSIS
      * putting more useful information in the warning messages


0.4   8-Mar-1998

      mkshadow
         - Bug (Mkshadow converted symbolic links into real path.)
           fixed.
      abs2rel  - modified to produce regularize path name.


0.5   30-Aug-1998 Barrie Slaymaker

    Added support for multiplatform use, fully implemented and tested only
    for Win32 based perl.  Published for review on comp.lang.perl

    Replaced common() for two reasons.  
       (1) having common() return the common string and then using s/// to
       chop it off the paths may have unexpected results if the paths have 
       RE metacharacters in them.  And '.' and '\' are meta characters.  
       (2) this is faster, since it saves calling common(), assembling the 
       common string, returning it, and calling s///.  Although an extra 
       join() is required.


0.6   05-Sep-1998

    Incorporated feedback from Tye McQueen to make REs more reliable and
    clear.

    Removed bug in rel2abs() that didn't see "C:/" and "/" as both being
    root directories.  This does mean that "C:/" and "D:/" both look 
    like "/", which is a silent bug.

    Added lots of comment inline, inspired by Tye's reminder that others
    might look to this as a style guide.  Thinking perhaps of adding
    a "valid path RE" that would be used to validate all path parameters
    and returns and issue warnings if they don't match.  This would be
    a service to the module user in case some garbage gets passed in.

    Moved the excising of "name/.." patterns into regularize()
       - simplifies abs2rel() and rel2abs()
       - reduces likelihood of having or fixing a bug in one place and not
         another
       - seems like this should be part of regularizing a path, anyway

    Fixed a bug in regularize() that would replace a valid root
    path beginning with the separator no matter what.  This means that
    'C:/' would always become '/', which is unexpected by the caller.
    The old code worked worked fine under Unix, but acted up under Win32.

    Changed behavior of regularize to change an empty path to '.'.

    Removed code that silently fixed some path errors in regularize.  This
    code fixed a path beginning with '/../' to begin with '/', and also
    fixed '//' to be '/'.  These two changes:
       - prevent the routine from silently patching over illegal parameter
         values that the user of this package should probably go fix
         anyway, IMHO.  In fact, by fixing the problem at the source, the
         API user is likely to discover some unexpected condition that was
         overlooked or misunderstood.
       - allow Win32 UNC pathnames to be used.  These begin with '//'.
       - speed up regularize()

    Added UNC pathname root recognition to $rootRE for Win32


0.7     07-Sep-1998

    Added @fsconfig, fssettype(), and related code.  This should allow
    for easy reconfiguration to all OSs with Unix or DOS like concepts
    of root and file separators.  VMS is still an open question due to
    it's [name] construct.


0.71    12-Sep-1998

    Fixed bug in $drive_letter creation in test.pl pointed out by Shigio.

    Adopted idiom from perlmod pod for exporting variables to fix problem
    getting to @EXPORT_OKed variables.


0.72    12-Sep-1998

    Removed spurious "$::" from the vars in @EXPORT_OK.

    Documented some limitations.

    Cleaned up fsconfig a bit
       - used "undef" for values that are not used
       - improved the MacOS settings a bit


0.80    12-Sep-1998

    Implemented splitpath(), joinpath(), splitdirectories(), 
    joindirectories(). This required adding the 'volume' and 'directory'
    parameters to all @fsconfig entries.

    Changed test.pl to test the above, started changing it towards using
    arrays instead of hashes for the stimulus / response data sets.  This
    is more convenient for testing the new routines, and delivers the
    expected test order, unliks takeing the keys() of a hash.

    Added print_error() to test.pl to make it easier to complain.

    Fixed bugs that assumed that '0' would never be passed
    in.  "if ($string)" was used in several places instead of 
    "if ( $string ne '' )".  This would have bitten on any length
    string of 0's, and VMS volume and directory names can sometimes
    have these.  A directory named '0' is also not impossible.

    Question: does VMS cwd() return path in Unix format or VMS format?
    
    Problem: $sepRE can't be used to detect single separators only in a
    situation like Win32 UNC names, and also detect separator sequences
    for idempotent directory separators.

    Improvement: flatten out fsconfig to be 2D insstead of 3D, and never
    derive an RE from a non-RE.  This will prevent anyone from forgetting
    to do an RE where they really shouldn't use the default RE.  And besides,
    they're not hard to do, and not too many can be automatically derived
    anyway.


0.81    12-Sep-1998

    Removed /o's from regexs, since the OS setting can be be changed in
    mid stream.

    Restored code that 'silently fixed some path errors' in regularize.  
    For some OSs, Unix and DOS, at least, these errors do not make
    invalid paths, so I put them back.  This code fixes a path beginning 
    with '/../' to begin with '/', and also fixed '//' to be '/'.  

    Changed name of $rootRE to $isrootRE, and adjusted $isrootRE values 
    to not account for volumes.  Note that $isrootRE may only be used in 
    testing for root, not for splitting off some
    prefix that means 'this is root'. In VMS, at least, a lack of a
    separator indicates root, while a leading separator indicates a
    relative path.

    Made abs2rel multiplatform.  Added multiplatform tests for abs2rel and
    rel2abs.

    Fixed bug that incorrectly turned '/name/..name2' in to 'name2'.


0.82 08-Nov-1998

    Traded @fsconfig in for an if/elsif tree.  This should be smaller,
    faster, and easier to understand, since I could eliminate a loop, a 
    helper routine, and 10 function calls or so.  The speed improvement 
    is necessary because of the shift to autodetecting unix style paths
    when in non-unix filesystem modes.

    Added beginnings of URL support.


0.83    05-Dec-1998

    Cleanup.  Move history to README, edit POD.

0.84

    Mostly bug fixes to URLs to allow Pod::Html to use us.

0.85

    Cleaned up regularization of m@/name/..@ to actually clean up
    m@name/..(/|$)@ so as to preserve root-ness. TODO: This cleanup
    could still be improved by making it clean up m@name/../@
    or m@(.)/name/..$@ or m@($isrootRE)name/..$@, preserving the
    leading root indicator. The current approach will end up
    leaving trailing slashes: /a/b/.. becomes /a/, not /a.

    Fixed rel2abs()'s handling of UNC names when the base (or cwd)
    is in the top-level shared directory.
    
    Noticed that treating the UNC volume specifier (\\server\sharename)
    as a volume, which prevents security problems like 

       rel2abs( '..\othersharename', '\\server\sharename' ) ;

    Considered calling regularize() in rel2abs() and abs2rel even when
    they are noops. This would make the behavior a little more complicated,
    which could be good or bad.

    Cleaned up joindirs() so that it won't introduce extra separators
    if any of the directory names already have separators in them.
    Made similar changes elsewhere, too.

    Converted regularize() to a function (it was a subroutine that
    modified a reference).

    Modified regularize to (1) preserve the trailing separator, if any,
    and (2) not use the default $sep when combining multiple separators
    so that we won't introduce a '/' instead of a '\' in Win32 land.

    Converted test suite to t/*.t format from test.pl.