README

Path: README
Last Update: Tue Sep 08 14:52:21 -0400 2009

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 library 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 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, and
   FileUtils, the priority is as follows:

   * File
   * Dir
   * FileUtils

   In other words, whichever of these defines a given method first is the
   method that is used by the pathname2 library.

Known Issues

   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.

   Any other issues should be reported on the project page at
   http://www.rubyforge.org/projects/shards

Future Plans

   Suggestions welcome.

License

   Artistic 2.0

Copyright

   (C) 2003-2009 Daniel J. Berger
   All rights reserved.

Warranty

   This library 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

[Validate]