== 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 and as a gem)
   * windows-pr 0.5.1 or later (available on the RAA and as a gem)
   
   The windows-pr package is only required on MS Windows.
   
== Installation, pure Ruby
=== Manual Installation
   rake test (optional)
   rake install
   
=== Gem Installation
   rake test (optional)
   gem install pathname2-<version>.gem
   
== Installation, C extension
   rake test_c (optional)
   rake install_c

== Synopsis
   require "pathname2"

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

   path1 + path2 # "/foo/bar/zap"
   path1 / path2 # "/foo/bar/zap" (same as +)
   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']

== Windows 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 Pathname in the standard library 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
     for symlinks (yet), though I'm not sure it warrants it.
   * 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.
   * Pathname#clean works slightly differently.  In the stdlib version,
     Pathname#clean("../a") returns "../a".  In this version, it returns "a".
     This affects other methods, such as Pathname#relative_path_from.
   * Accepts file urls and converts them to paths automatically, e.g.
     file:///foo%20bar/baz becomes '/foo bar/baz'.
   * Adds a Kernel level +pn+ method as a shortcut.
   * Allows you to add paths together with the '/' operator.
     
== 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.
   
   In Ruby 1.8.3 and 1.8.4 you will see a failure in the test suite regarding
   'fu_world_writable?' from FileUtils.  You can ignore this.  That method is
   supposed to be private.  See ruby-core:7383.

== Future Plans
   Because ftools is more or less deprecated, and FileUtils can generally do
   everything ftools can do, and better, I'm going to remove ftools in the
   1.6.0 release.
   
== License
   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)
