path 1.3.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2011-2012 Benoit Daloze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,183 @@
+# Path - a Path manipulation library
+
+[Path](http://rubydoc.info/github/eregon/path/master/Path) is a library to manage paths.  
+It is similar to Pathname, but has some extra goodness.  
+The method names are intended to be short and explicit, and avoid too much duplication like having 'name' or 'path' in the method name.
+
+I believe the object-oriented approach to manipulate paths is very elegant and useful.  
+Paths are naturally the subject of their methods and even if they are simple Strings behind, they carry way much more information and deserve a first-class status.
+
+Also, using a path library like this avoid to remember in which class the functionality is implemented, everything is in one place (if not, please open an issue!).
+
+## Installation
+
+    gem install path
+
+## Links
+
+* [GitHub](https://github.com/eregon/path)
+* [YARD Documentation](http://rubydoc.info/github/eregon/path/master/file/README.md)
+* [Changelog](https://github.com/eregon/path/blob/master/Changelog.md)
+
+## API
+
+See the [Path](http://rubydoc.info/github/eregon/path/master/Path) class documentation for details.
+
+All the useful methods of `File` (and so `IO`) and `Dir` should be included.  
+Most methods of `FileUtils` should be there too.
+
+### creation
+
+``` ruby
+Path.new('/usr/bin')
+Path['/usr/bin']
+Path('/usr/bin') # unless NO_PATH_GLOBAL_FUNCTION is defined
+
+Path.new('~myuser/path') # expanded if it begins with ~
+
+# Separators are replaced by / on systems having File::ALT_SEPARATOR
+Path.new('win\sepa\rator') # => #<Path win/sepa/rator>
+
+Path.new('/usr', 'bin')
+%w[foo bar].map(&Path) # => [Path('foo'), Path('bar')]
+```
+
+``` ruby
+Path.file           # == Path(__FILE__).expand
+Path.dir            # == Path(File.dirname(__FILE__)).expand
+Path.relative(path) # == Path(File.expand_path("../#{path}", __FILE__))
+Path.home or Path.~ # == Path(File.expand_path('~'))
+Path.~(user)        # == Path(File.expand_path("~#{user}"))
+```
+
+### temporary
+
+``` ruby
+Path.tmpfile
+Path.tmpdir
+```
+
+### aliases
+
+* expand => expand\_path
+* relative\_to => relative\_path\_from
+
+### parts
+
+Path can split a path in two ways:
+
+The first way is the one done by File methods (dirname, basename, extname).  
+
+The second is Path's own way in which the base is given without the extension and the extension is given without the leading dot.  
+The rationale behind this is to have a true three-components path, splitting on the / and the . (See [this issue](https://github.com/eregon/path/pull/8#issuecomment-3499030) for details)
+
+       dirname     basename
+     ____________   ______
+    /            \ /      \
+    /some/path/dir/file.ext
+    \____________/ \__/ \_/
+          dir      base ext
+
+    path = dirname / basename
+    path = dirname / basename(extname) extname
+    path = dir / base [. ext]
+
+* dirname: "/some/path/dir"
+* basename: "file.ext"
+* extname: ".ext"
+
+<!-- -->
+
+* dir: alias of dirname: "/some/paths/dir"
+* base: basename(extname), the basename without the extension: "file"
+* ext: extname without the leading dot: "ext"
+
+<!-- -->
+
+### join
+
+* join(*parts)
+* /: join paths (as Pathname#+)
+
+```ruby
+Path('/usr')/'bin'
+```
+
+### extensions
+
+* add\_ext / add\_extension
+* rm\_ext / without\_extension
+* sub\_ext(new\_ext) / replace\_extension(new\_ext)
+
+### glob
+
+* children: files under self, without . and ..
+* glob: relative glob to self, yield absolute paths
+
+### structure
+
+* parent: parent directory (don't use #dirname more than once, use #parent instead)
+* ascend, ancestors: self and all the parent directories
+* descend: in the reverse order
+* backfind: ascends the parents until it finds the given path
+
+``` ruby
+# Path.backfind is Path.here.backfind
+Path.backfind('lib') # => Path's lib folder
+
+# It accepts XPath-like context
+Path.backfind('.[.git]') # => the root of this repository
+```
+
+### IO
+
+* read
+* write(contents)
+* append(contents)
+
+### management
+
+* mkdir
+* mkdir\_p
+* rm\_rf
+
+### require
+
+* Path.require\_tree: require all .rb files recursively (in alphabetic order)
+
+### relocate
+
+``` ruby
+from = Path('pictures')
+to   = Path('output/public/thumbnails')
+earth = Path('pictures/nature/earth.jpg')
+
+earth.relocate(from, to, '.png') { |rel| "#{rel}-200" }
+# => #<Path output/public/thumbnails/nature/earth-200.png>
+```
+
+## Transition from String/Pathname
+
+One aim of Path is to help the user make the transition coming from
+String (not using a path library), Pathname, or another library.
+
+To this intend, [`Path + config`](http://rubydoc.info/github/eregon/path/master/Path#%2B-class_method) allows to configure the behavior of `Path#+`.
+
+Coming from String, one should use `Path + :string`, and run ruby with the verbose option (`-w`),
+which will show where `+` is used as String concatenation.
+
+Coming from a path library using `+` as #join, one should just use the default (`Path + :warning`),
+which will show where `+` is used.
+
+## Status
+
+This is still in the early development stage, you should expect many additions and some changes.
+
+## Author
+
+Benoit Daloze - eregon
+
+## Contributors
+
+Bernard Lambeau - blambeau  
+Ravil Bayramgalin - brainopia

data/lib/epath.rb

@@ -0,0 +1,2 @@
+# For compatibility with old gem name
+require File.expand_path('../path.rb', __FILE__)

data/lib/path.rb

@@ -0,0 +1,159 @@
+# Path - a Path manipulation library
+
+Dir.glob(File.expand_path('../path/*.rb',__FILE__)) { |file| require file }
+
+require 'tempfile'
+
+class Path
+  class << self
+    # {Path} to the current file +Path(__FILE__)+.
+    def file(from = nil)
+      from ||= caller # this can not be moved as a default argument, JRuby optimizes it
+                                     # v This : is there to define a group without capturing
+      new(from.first.rpartition(/:\d+(?:$|:in )/).first).expand
+    end
+    alias :here :file
+
+    # {Path} to the directory of this file: +Path(__FILE__).dir+.
+    def dir(from = nil)
+      from ||= caller # this can not be moved as a default argument, JRuby optimizes it
+      file(from).dir
+    end
+
+    # {Path} relative to the directory of this file.
+    def relative(path, from = nil)
+      from ||= caller # this can not be moved as a default argument, JRuby optimizes it
+      new(path).expand dir(from)
+    end
+
+    # A {Path} to the home directory of +user+ (defaults to the current user).
+    # The form with an argument (+user+) is not supported on Windows.
+    def ~(user = '')
+      new("~#{user}")
+    end
+    alias :home :~
+
+    # Same as +Path.file.backfind(path)+. See {#backfind}.
+    def backfind(path)
+      file(caller).backfind(path)
+    end
+
+    # @yieldparam [Path] tmpfile
+    def tmpfile(basename = '', tmpdir = nil, options = nil)
+      tempfile = Tempfile.new(basename, *[tmpdir, options].compact)
+      file = new tempfile
+      if block_given?
+        begin
+          yield file
+        ensure
+          tempfile.close!
+        end
+      end
+      file
+    end
+    alias :tempfile :tmpfile
+
+    # @yieldparam [Path] tmpdir
+    def tmpdir(prefix_suffix = nil, *rest)
+      require 'tmpdir'
+      dir = new Dir.mktmpdir(prefix_suffix, *rest)
+      if block_given?
+        begin
+          yield dir
+        ensure
+          FileUtils.remove_entry_secure(dir) rescue nil
+        end
+      end
+      dir
+    end
+
+    # @yieldparam [Path] tmpdir
+    def tmpchdir(prefix_suffix = nil, *rest)
+      tmpdir do |dir|
+        dir.chdir do
+          yield dir
+        end
+      end
+    end
+  end
+
+  # Whether +self+ is inside +ancestor+, such that +ancestor+ is an ancestor of +self+.
+  # This is pure String manipulation. Paths should be absolute.
+  # +self+ is considered to be inside itself.
+  def inside? ancestor
+    @path == ancestor.to_s or @path.start_with?("#{ancestor}/")
+  end
+
+  # The opposite of {#inside?}.
+  def outside? ancestor
+    !inside?(ancestor)
+  end
+
+  # Ascends the parents until it finds the given +path+.
+  #
+  #   Path.backfind('lib') # => the lib folder
+  #
+  # It accepts an XPath-like context:
+  #
+  #   Path.backfind('.[.git]') # => the root of the repository
+  def backfind(path)
+    condition = path[/\[(.*)\]$/, 1] || ''
+    path = $` unless condition.empty?
+
+    result = ancestors.find { |ancestor| (ancestor/path/condition).exist? }
+    result/path if result
+  end
+
+  # Relocates this path somewhere else.
+  #
+  # Without a block, this method is a simple shorcut for a longer
+  # expression that proves difficult to remember in practice:
+  #
+  #   to / (self.sub_ext(new_ext) % from)
+  #
+  # That is, it relocates the original path to a target folder +to+
+  # appended with the relative path from a source folder +from+. An
+  # optional new extension can also be specified, as it is a common
+  # use case.
+  #
+  # With a block, the relative path is passed to the block for user
+  # update, without the last extension. +new_ext+ is added after (or
+  # the original extension if not provided).
+  #
+  #   from = Path('pictures')
+  #   to   = Path('output/public/thumbnails')
+  #   earth = from / 'nature/earth.jpg'
+  #
+  #   earth.relocate(from, to)
+  #   # => #<Path output/public/thumbnails/nature/earth.jpg>
+  #
+  #   earth.relocate(from, to, '.png') { |rel|
+  #     "#{rel}-200"
+  #   }
+  #   # => #<Path output/public/thumbnails/nature/earth-200.png>
+  def relocate(from, to, new_ext = ext, &updater)
+    updater ||= lambda { |path| path }
+    renamer = lambda { |rel|
+      Path(updater.call(rel.rm_ext)).add_ext(new_ext)
+    }
+    to / renamer.call(self % from)
+  end
+
+  # Setup
+  register_loader 'yml', 'yaml' do |path|
+    require 'yaml'
+    YAML.load_file(path)
+  end
+
+  register_loader 'json' do |path|
+    require 'json'
+    JSON.load(path.read)
+  end
+
+  register_loader 'gemspec' do |path|
+    eval path.read
+  end
+end
+
+# to meet everyone's expectations and for compatibility with old gem name
+EPath = Path

data/lib/path/compatibility.rb

@@ -0,0 +1,60 @@
+class Path
+  private
+
+  if File.respond_to?(:realpath) and File.respond_to?(:realdirpath)
+    def real_path_internal(strict = false, basedir = nil)
+      strict ? File.realpath(@path, basedir) : File.realdirpath(@path, basedir)
+    end
+  else
+    def realpath_rec(prefix, unresolved, h, strict, last = true)
+      resolved = []
+      until unresolved.empty?
+        n = unresolved.shift
+        if n == '..'
+          resolved.pop
+        else
+          path = prepend_prefix(prefix, resolved + [n])
+          if h.include? path
+            if h[path] == :resolving
+              raise Errno::ELOOP.new(path)
+            else
+              prefix, *resolved = h[path]
+            end
+          else
+            begin
+              s = File.lstat(path)
+            rescue Errno::ENOENT => e
+              raise e if strict || !last || !unresolved.empty?
+              resolved << n
+              break
+            end
+            if s.symlink?
+              h[path] = :resolving
+              link_prefix, link_names = split_names(File.readlink(path))
+              if link_prefix == '' # if link is relative
+                link_prefix, link_names = prefix, resolved.concat(link_names)
+              end
+              prefix, *resolved = h[path] = realpath_rec(link_prefix, link_names, h, strict, unresolved.empty?)
+            else
+              resolved << n
+              h[path] = [prefix, *resolved]
+            end
+          end
+        end
+      end
+      return prefix, *resolved
+    end
+
+    def real_path_internal(strict = false, basedir = nil)
+      path = @path
+      path = File.join(basedir, path) if basedir and relative?
+      prefix, names = split_names(path)
+      if prefix == ''
+        prefix, names2 = split_names(Dir.pwd)
+        names = names2.concat(names)
+      end
+      prefix, *names = realpath_rec(prefix, names, {}, strict)
+      prepend_prefix(prefix, names)
+    end
+  end
+end

data/lib/path/dir.rb

@@ -0,0 +1,147 @@
+class Path
+  class << self
+    # @!group Directory
+
+    # Returns or yields Path objects. See +Dir.glob+.
+    # @yieldparam [Path] path
+    def glob(pattern, flags = 0)
+      if block_given?
+        Dir.glob(pattern, flags) { |f| yield new(f) }
+      else
+        Dir.glob(pattern, flags).map(&Path)
+      end
+    end
+
+    # Returns the current working directory as a Path. See +Dir.getwd+.
+    def Path.getwd
+      new Dir.getwd
+    end
+    alias :pwd :getwd
+  end
+
+  # @!group Directory
+
+  # Iterates over the entries (files and subdirectories) in the directory.
+  #
+  #   Path("/usr/local").each_entry { |entry| p entry } # =>
+  #   #<Path .>
+  #   #<Path ..>
+  #   #<Path lib>
+  #   #<Path share>
+  #   # ...
+  #
+  # @deprecated Use {#each_child} instead.
+  #   This method is deprecated since it is too low level and likely useless in Ruby.
+  #   But it is there for the sake of compatibility with Dir.foreach and Pathname#each_entry.
+  # @yieldparam [Path] entry
+  def each_entry(&block)
+    Dir.foreach(@path) { |f| yield Path.new(f) }
+  end
+
+  # Create the referenced directory and returns self. See +Dir.mkdir+.
+  def mkdir(*args)
+    Dir.mkdir(@path, *args)
+    self
+  end
+
+  # Remove the referenced directory. See +Dir.rmdir+.
+  def rmdir
+    Dir.rmdir(@path)
+  end
+
+  # See +Dir.open+.
+  # @yieldparam [Dir] dir
+  def opendir(&block)
+    Dir.open(@path, &block)
+  end
+
+  # Returns or yields Path objects. See +Dir.glob+.
+  # @yieldparam [Path] path
+  def glob(pattern, flags = 0)
+    if block_given?
+      Dir.glob(join(pattern), flags) { |f| yield Path.new(f) }
+    else
+      Dir.glob(join(pattern), flags).map(&Path)
+    end
+  end
+
+  # Return the entries (files and subdirectories) in the directory.
+  # Each Path only contains the filename.
+  # The result may contain the current directory #<Path .> and the parent directory #<Path ..>.
+  #
+  #   Path('/usr/local').entries
+  #   # => [#<Path share>, #<Path lib>, #<Path .>, #<Path ..>, <Path bin>, ...]
+  #
+  # @deprecated Use {#children} instead.
+  #   This method is deprecated since it is too low level and likely useless in Ruby.
+  #   But it is there for the sake of compatibility with Dir.entries (and Pathname#entries).
+  def entries
+    Dir.entries(@path).map(&Path)
+  end
+
+  # Changes the current working directory of the process to self. See Dir.chdir.
+  # The recommended way to use it is to use the block form, or not use it all!
+  def chdir(&block)
+    Dir.chdir(@path, &block)
+  end
+
+  # Returns the children of the directory (files and subdirectories, not
+  # recursive) as an array of Path objects. By default, the returned
+  # paths will have enough information to access the files. If you set
+  # +with_directory+ to +false+, then the returned paths will contain the
+  # filename only.
+  #
+  # For example:
+  #   pn = Path("/usr/lib/ruby/1.8")
+  #   pn.children
+  #       # -> [ #<Path /usr/lib/ruby/1.8/English.rb>,
+  #              #<Path /usr/lib/ruby/1.8/Env.rb>,
+  #              #<Path /usr/lib/ruby/1.8/abbrev.rb>, ... ]
+  #   pn.children(false)
+  #       # -> [ #<Path English.rb>, #<Path Env.rb>, #<Path abbrev.rb>, ... ]
+  #
+  # Note that the results never contain the entries +.+ and +..+ in
+  # the directory because they are not children.
+  def children(with_directory=true)
+    with_directory = false if @path == '.'
+    result = []
+    Dir.foreach(@path) { |e|
+      next if e == '.' || e == '..'
+      if with_directory
+        result << Path.new(@path, e)
+      else
+        result << Path.new(e)
+      end
+    }
+    result
+  end
+
+  # Iterates over the children of the directory (files and subdirectories, not recursive).
+  # By default, the yielded paths will have enough information to access the files.
+  # If you set +with_directory+ to +false+, then the returned paths will contain the filename only.
+  #
+  #   Path("/usr/local").each_child { |f| p f } # =>
+  #       #<Path /usr/local/share>
+  #       #<Path /usr/local/bin>
+  #       #<Path /usr/local/games>
+  #       #<Path /usr/local/lib>
+  #       #<Path /usr/local/include>
+  #       #<Path /usr/local/sbin>
+  #       #<Path /usr/local/src>
+  #       #<Path /usr/local/man>
+  #
+  #   Path("/usr/local").each_child(false) { |f| p f } # =>
+  #       #<Path share>
+  #       #<Path bin>
+  #       #<Path games>
+  #       #<Path lib>
+  #       #<Path include>
+  #       #<Path sbin>
+  #       #<Path src>
+  #       #<Path man>
+  #
+  # @yieldparam [Path] child
+  def each_child(with_directory=true, &b)
+    children(with_directory).each(&b)
+  end
+end