Path: readme Last Update: Sat Dec 17 22:21:45 Mountain Standard Time 2005

## Description

   A drop in replacement for the current Pathname class.


## Prerequisites

   * Ruby 1.8.0 or later
* facade 1.0.0 or later (available on the RAA)


## Installation, pure Ruby

### Manual Installation

   ruby test/tc_pathname.rb (Unix, optional)
ruby test/tc_pathname_win.rb (Windows, optional)
ruby install.rb


### Gem Installation

   ruby test/tc_pathname.rb (Unix, optional)
ruby test/tc_pathname_win.rb (Windows, optional)
gem install pathname2-<version>.gem


## Installation, C extension

   cd to the 'ext' directory.
ruby extconf.rb
make
run appropriate test (optional)
make install


## Synopsis

   require "pathname2"

# Unix
path1 = "/foo/bar/baz"
path2 = "../zap"

path1 + path2 # "/foo/bar/zap"
path1.exists? # Does this path exist?
path1.dirname # "/foo/bar"
path1.to_a    # ['foo','bar','baz']

# Windows
path1 = "C:/foo/bar/baz"
path2 = "../zap"

path1 + path2 # "C:\\foo\\bar\\zap"
path1.root    # "C:\\"
path1.to_a    # ['C:','foo','bar','baz']


## Win32 Notes

   All forward slashes are converted to backslashes for Pathname objects.


## Differences between Unix and Windows

   If your pathname consists solely of ".", or "..", the return
value for Pathname#clean will be different. On Win32, "\\" is returned,
while on Unix "." is returned.  I consider this an extreme edge case and
will not worry myself with it.


## Differences between the old version and this version

   * It is a subclass of String (and thus, mixes in Enumerable).
* It has sensical to_a and root instance methods.
* It works on Windows and Unix.  The current implementation does not work
with Windows path names very well, and not at all when it comes to UNC
paths.
* The Pathname#cleanpath method works differently - it always returns
a canonical pathname.  In addition, there is no special consideration
* The Pathname#+ method auto cleans.
* It uses a facade for all File and Dir methods, as well as all ftools
methods and most FileUtils methods.


## Method Priority

   Because there is some overlap in method names between File, Dir, ftools
and FileUtils, the priority is as follows:

* File
* Dir
* ftools
* FileUtils

In other words, whichever of these defines a given method first is the
method that is used by the pathname2 package.  For example, the
Pathname#safe_unlink method used is the one defined in ftools.rb,
not the one defined in the FileUtils module.


## Known Issues

   You cannot pass a frozen string to the constructor on Windows using the
pure Ruby version.  There is an unresolved issue with Win32API and frozen
objects.

Pathname#glob is not yet implemented in the C version.
Pathname#find is not implemented properly in the C version.


   Ruby's


## Warranty

   This package is provided "as is" and without any express or
implied warranties, including, without limitation, the implied
warranties of merchantability and fitness for a particular purpose.


## Author

   Daniel J. Berger
djberg96 at gmail dot com
imperator on IRC (irc.freenode.net)