epath 0.0.1 → 0.1.0

data/README.md

@@ -1,4 +1,4 @@
-# Path - Enhanced Pathname
+# Path - a Path manipulation library
 
 Path is a library to manage paths.  
 It is similar to Pathname, but has some extra goodness.  
@@ -9,6 +9,11 @@ Paths are naturally the subject of their methods and even if they are simple Str
 
 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!).
 
+## Links
+
+* [GitHub](https://github.com/eregon/epath)
+* [YARD Documentation](http://rubydoc.info/github/eregon/epath/master/file/README.md)
+
 ## API
 
 All the useful methods of `File` (and so `IO`) and `Dir` should be included.  
@@ -26,10 +31,10 @@ Path.new('/usr', 'bin')
 ```
 
 ``` ruby
-Path.here # == Path(__FILE__).expand
-Path.dir # == Path(File.dirname(__FILE__)).expand
+Path.file           # == Path(__FILE__).expand
+Path.dir            # == Path(File.dirname(__FILE__)).expand
 Path.relative(path) # == Path(File.expand_path("../#{path}", __FILE__))
-Path.home # == Path(File.expand_path('~'))
+Path.home           # == Path(File.expand_path('~'))
 ```
 
 ### temporary
@@ -41,24 +46,55 @@ Path.tmpdir
 
 ### aliases
 
-* expand => expand_path
-* relative_to => relative_path_from
+* expand => expand\_path
+* relative\_to => relative\_path\_from
 
 ### parts
 
-* base: basename(extname)
-* dir: alias of dirname
-* ext: extname without the leading dot
-* /: join paths
+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/epath/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'
 ```
 
-These method names are too long, any idea to make them shorter and clear?
+### extensions
 
-* without_extension
-* replace_extension(new_ext)
+* add\_ext / add\_extension
+* rm\_ext / without\_extension
+* sub\_ext(new\_ext) / replace\_extension(new\_ext)
 
 ### glob
 
@@ -67,13 +103,15 @@ These method names are too long, any idea to make them shorter and clear?
 
 ### structure
 
-* ancestors: self and all the parent directories
+* 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
+
+# It accepts XPath-like context
 Path.backfind('.[.git]') # => the root of this repository
 ```
 
@@ -86,12 +124,12 @@ Path.backfind('.[.git]') # => the root of this repository
 ### management
 
 * mkdir
-* mkdir_p
-* rm_rf
+* mkdir\_p
+* rm\_rf
 
-### Incompatibilities with Pathname
+### require
 
-* #entries never returns . and ..
+* Path.require\_tree: require all .rb files recursively (in alphabetic order)
 
 ## Status
 
@@ -101,6 +139,7 @@ This is still in the early development stage, you should expect many additions a
 
 Benoit Daloze - eregon
 
-### Contributors
+## Contributors
 
-Bernard Lambeau - blambeau
+Bernard Lambeau - blambeau  
+Ravil Bayramgalin - brainopia

data/epath.gemspec

@@ -5,5 +5,7 @@ Gem::Specification.new do |s|
   s.email = 'eregontp@gmail.com'
   s.homepage = 'https://github.com/eregon/epath'
   s.files = Dir['lib/**/*.rb'] + %w[README.md LICENSE epath.gemspec]
-  s.version = '0.0.1'
+  s.version = '0.1.0'
+
+  s.add_development_dependency 'rspec'
 end

data/lib/epath.rb

@@ -1,34 +1,20 @@
-# Enchanced Pathname
-# Use the composite pattern with a Pathname
+# Path - a Path manipulation library
+
+Dir.glob(File.expand_path('../epath/*.rb',__FILE__)) { |file| require file }
 
-require File.expand_path('../epath/implementation', __FILE__)
 require 'tempfile'
 
 class Path
-  DOTS = %w[. ..]
-
   class << self
-    def new(*args)
-      if args.size == 1 and Path === args[0]
-        args[0]
-      else
-        super(*args)
-      end
-    end
-    alias_method :[], :new
-
-    def to_proc
-      lambda { |path| new(path) }
-    end
-
-    def here(from = nil)
-      from ||= caller
-      new(from.first.split(/:\d+(?:$|:in)/).first).expand
+    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_method :file, :here
+    alias :here :file
 
     def dir(from = nil)
-      from ||= caller
+      from ||= caller # this can not be moved as a default argument, JRuby optimizes it
       file(from).dir
     end
 
@@ -41,7 +27,7 @@ class Path
     end
 
     def backfind(path)
-      here(caller).backfind(path)
+      file(caller).backfind(path)
     end
 
     def tmpfile(basename = '', tmpdir = nil, options = nil)
@@ -57,7 +43,7 @@ class Path
       end
       file
     end
-    alias_method :tempfile, :tmpfile
+    alias :tempfile :tmpfile
 
     def tmpdir(prefix_suffix = nil, *rest)
       require 'tmpdir'
@@ -71,108 +57,27 @@ class Path
       end
       dir
     end
-  end
-
-  def initialize(*parts)
-    path = parts.size > 1 ? parts.join(File::SEPARATOR) : parts.first
-    if Tempfile === path
-      @_tmpfile = path # We would not want it to be GC'd
-      @path = path.path
-    elsif String === path
-      @path = path.dup
-    else
-      @path = path.to_s
-    end
-    taint if @path.tainted?
-  end
-
-  def / part
-    join part.to_s
-  end
-
-  def base # basename(extname)
-    basename(extname)
-  end
-
-  def ext # extname without leading .
-    ext = extname
-    ext.empty? ? ext : ext[1..-1]
-  end
-
-  def without_extension # rm_ext
-    dir / base
-  end
-
-  # NOTE: Pathname has a similar feature named sub_ext
-  # It might be a better method name
-  def replace_extension(ext)
-    ext = ".#{ext}" unless ext.start_with? '.'
-    Path.new(without_extension.to_s + ext)
-  end
 
-  def entries
-    (Dir.entries(@path) - DOTS).map { |entry| Path.new(@path, entry).cleanpath }
-  end
-
-  def glob(pattern, flags = 0)
-    Dir.glob(join(pattern), flags).map(&Path)
-  end
-
-  def rm
-    FileUtils.rm(@path)
-    self
-  end
-
-  def rm_f
-    FileUtils.rm_f(@path)
-    self
-  end
-
-  def rm_rf
-    FileUtils.rm_rf(@path)
-    self
-  end
-
-  def mkdir_p
-    FileUtils.mkdir_p(@path)
-    self
-  end
-
-  def write(contents, open_args = nil)
-    if IO.respond_to? :write
-      IO.write(@path, contents, *[open_args].compact)
-    else
-      open('w', *[open_args].compact) { |f| f.write(contents) }
+    def tmpchdir(prefix_suffix = nil, *rest)
+      tmpdir do |dir|
+        dir.chdir do
+          yield dir
+        end
+      end
     end
   end
 
-  def append(contents, open_args = nil)
-    if IO.respond_to? :write
-      open_args = (Array(open_args) << {:mode => 'a'})
-      IO.write(@path, contents, *open_args.compact)
-    else
-      open('a', *[open_args].compact) { |f| f.write(contents) }
-    end
-  end
+  alias :/ :+
 
-  def to_sym
-    to_s.to_sym
-  end
+  alias :relative_to :relative_path_from
+  alias :% :relative_path_from
 
-  def relative_to other
-    relative_path_from Path.new other
+  def inside? ancestor
+    @path == ancestor.to_s or @path.start_with?("#{ancestor}/")
   end
-  alias_method :%, :relative_to
 
-  def ancestors
-    ancestors = lambda do |y|
-      y << path = expand
-      until (path = path.parent).root?
-        y << path
-      end
-      y << path
-    end
-    RUBY_VERSION > '1.9' ? Enumerator.new(&ancestors) : ancestors.call([])
+  def outside? ancestor
+    !inside?(ancestor)
   end
 
   def backfind(path)
@@ -183,14 +88,20 @@ class Path
     result/path if result
   end
 
-  alias_method :expand, :expand_path
-  alias_method :dir, :dirname
-end
+  # Setup
+  register_loader 'yml', 'yaml' do |path|
+    require 'yaml'
+    YAML.load_file(path)
+  end
 
-EPath = Path # to meet everyone's expectations
+  register_loader 'json' do |path|
+    require 'json'
+    JSON.load(path.read)
+  end
 
-unless defined? NO_EPATH_GLOBAL_FUNCTION
-  def Path(*args)
-    Path.new(*args)
+  register_loader 'gemspec' do |path|
+    eval path.read
   end
 end
+
+EPath = Path # to meet everyone's expectations

data/lib/epath/dir.rb

@@ -0,0 +1,123 @@
+class Path
+  class << self
+    # Returns or yields Path objects. See +Dir.glob+.
+    def glob(*args) # :yield: path
+      if block_given?
+        Dir.glob(*args) { |f| yield new(f) }
+      else
+        Dir.glob(*args).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
+
+  # Iterates over the entries (files and subdirectories) in the directory.
+  # It yields a Path object for each entry.
+  def each_entry(&block) # :yield: path
+    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+.
+  def opendir(&block) # :yield: dir
+    Dir.open(@path, &block)
+  end
+
+  def glob(pattern, flags = 0)
+    Dir.glob(join(pattern), flags).map(&Path)
+  end
+
+  # [DEPRECATED] 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>, ...]
+  #
+  # 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)
+  #
+  # Use #children instead.
+  def entries
+    Dir.entries(@path).map(&Path)
+  end
+
+  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).
+  # It yields Path object for each child.
+  # 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>
+  def each_child(with_directory=true, &b)
+    children(with_directory).each(&b)
+  end
+end