File: README [pathname2-1.7.3 Documentation]

### Home Classes Methods

### Files

- CHANGES
- MANIFEST
- README

### Class Index

Quicksearch

- Pathname
- Pathname::Error
- Kernel
- String

No matching classes.

## Description

    A drop-in replacement for the current Pathname class.

## Prerequisites

    * facade
    * ffi (Windows only)
    * test-unit (testing only)

## Installation

    gem install pathname2

## Synopsis

    require 'pathname2'

    # Unix
    path1 = Pathname.new("/foo/bar/baz")
    path2 = Pathname.new("../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 = Pathname.new("C:/foo/bar/baz")
    path2 = Pathname.new("../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
    https://github.com/djberg96/pathname2

## Future Plans

    Suggestions welcome.

## License

    Artistic 2.0

## Copyright

    (C) 2003-2014 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]

Generated with the Darkfish Rdoc Generator 2.