epath 0.2.0 → 0.3.0

data/README.md

@@ -17,6 +17,7 @@ Also, using a path library like this avoid to remember in which class the functi
 
 * [GitHub](https://github.com/eregon/epath)
 * [YARD Documentation](http://rubydoc.info/github/eregon/epath/master/file/README.md)
+* [Changelog](https://github.com/eregon/epath/blob/master/Changelog.md)
 
 ## API
 
@@ -144,6 +145,30 @@ Path.backfind('.[.git]') # => the root of this repository
 
 * 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/epath/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 were `+` is used as String concatenation.
+
+Coming from a path library using `+` as #join, one should just use the default (`Path + :warning`),
+which will show were `+` is used as #join.
+
 ## Status
 
 This is still in the early development stage, you should expect many additions and some changes.

data/lib/epath.rb

@@ -103,6 +103,41 @@ class Path
     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'

data/lib/epath/fileutils.rb

@@ -33,12 +33,6 @@ class Path
   end
   alias :safe_unlink :rm_f
 
-  # Removes the file or directory recursively, using +FileUtils.rm_r+.
-  def rm_r
-    FileUtils.rm_r(@path)
-    self
-  end
-
   # Removes the file or directory recursively, ignoring errors,
   # using +FileUtils.rm_f+.
   def rm_rf

data/lib/epath/identity.rb

@@ -22,18 +22,27 @@ class Path
 
   # @!group Identity
 
+  # Returns the +path+ as a String.
+  # {#path} is implemented for better readability (+file.path+ instead of +file.to_s+) and as an accessor.
+  # {#to_path} is implemented so Path objects are usable with +open+, etc.
+  # {#to_str} is implemented so Path objects are usable with +open+, etc with Ruby 1.8 (it is not defined in Ruby 1.9).
+  attr_reader :path
+  alias :to_s :path
+  alias :to_path :path
+  alias :to_str :path if RUBY_VERSION < '1.9'
+
   # Compare this path with +other+. The comparison is string-based.
   # Be aware that two different paths (+foo.txt+ and +./foo.txt+)
   # can refer to the same file.
   def == other
-    Path === other and @path == other.to_path
+    Path === other and @path == other.path
   end
   alias :eql? :==
 
   # Provides for comparing paths, case-sensitively.
   def <=>(other)
     return nil unless Path === other
-    @path.tr('/', "\0") <=> other.to_s.tr('/', "\0")
+    @path.tr('/', "\0") <=> other.path.tr('/', "\0")
   end
 
   # The hash value of the +path+.
@@ -41,17 +50,6 @@ class Path
     @path.hash
   end
 
-  # Returns the +path+ as a String.
-  def to_s
-    @path
-  end
-
-  # to_path is implemented so Path objects are usable with File.open, etc.
-  alias :to_path :to_s
-
-  # to_str is implemented so Path objects are usable with File.open, etc in Ruby 1.8.
-  alias :to_str :to_s if RUBY_VERSION < '1.9'
-
   # Returns the +path+ as a Symbol.
   def to_sym
     @path.to_sym

data/lib/epath/implementation.rb

@@ -39,6 +39,19 @@ class Path
     init
   end
 
+  # JSON dumping.
+  def to_json(*args)
+    {
+      'json_class' => 'Path',
+      'data'       => @path
+    }.to_json(*args)
+  end
+
+  # JSON loading.
+  def self.json_create json
+    new json['data']
+  end
+
   # Marshal dumping.
   def marshal_dump
     @path
@@ -50,20 +63,17 @@ class Path
     init
   end
 
-  # Returns clean path of +self+ with consecutive slashes and useless dots removed.
+  # Returns a cleaned version of +self+ with consecutive slashes and useless dots removed.
   # The filesystem is not accessed.
   #
   # If +consider_symlink+ is +true+, then a more conservative algorithm is used
   # to avoid breaking symbolic linkages. This may retain more +..+
   # entries than absolutely necessary, but without accessing the filesystem,
   # this can't be avoided. See {#realpath}.
-  def cleanpath(consider_symlink=false)
-    if consider_symlink
-      cleanpath_conservative
-    else
-      cleanpath_aggressive
-    end
+  def clean(consider_symlink = false)
+    consider_symlink ? cleanpath_conservative : cleanpath_aggressive
   end
+  alias :cleanpath :clean
 
   # #parent returns the parent directory.
   # This can be chained.
@@ -81,12 +91,58 @@ class Path
   def /(other)
     Path.new(plus(@path, other.to_s))
   end
-  alias :+ :/
 
-  # Path#join joins paths.
+  # Configures the behavior of {Path#+}. The default is +:warning+.
+  #
+  #   Path + :defined # aliased to Path#/
+  #   Path + :warning # calls Path#/ but warns
+  #   Path + :error   # not defined
+  #   Path + :string  # like String#+. Warns if $VERBOSE (-w)
+  #
+  # @param config [:defined, :warning, :error, :string] the configuration value
+  def Path.+(config)
+    unless [:defined, :warning, :error, :string].include? config
+      raise ArgumentError, "Invalid configuration: #{config.inspect}"
+    end
+    if @plus_configured
+      raise "Path.+ has already been called: #{@plus_configured}"
+    end
+    remove_method :+ if method_defined? :+
+    case config
+    when :defined
+      alias :+ :/
+    when :warning
+      def +(other)
+        warn 'Warning: use of deprecated Path#+ as Path#/: ' <<
+             "#{inspect} + #{other.inspect}\n#{caller.first}"
+        self / other
+      end
+    when :error
+      # nothing to do, the method has been removed
+    when :string
+      def +(other)
+        warn 'Warning: use of deprecated Path#+ as String#+: ' <<
+             "#{inspect} + #{other.inspect}\n#{caller.first}" if $VERBOSE
+        Path(to_s + other.to_s)
+      end
+    end
+    @plus_configured = caller.first
+  end
+
+  @plus_configured = nil # Initialization
+  Path + :warning
+  @plus_configured = nil # Let the user overrides this default configuration
+
+  # @!method +(other)
+  #   The behavior depends on the configuration with Path.{Path.+}.
+  #   It might behave as {Path#/}, String#+, give warnings,
+  #   or not be defined at all.
+
+  # Joins paths.
   #
-  # <tt>path0.join(path1, ..., pathN)</tt> is the same as
-  # <tt>path0 / path1 / ... / pathN</tt>.
+  #   path0.join(path1, ..., pathN)
+  #   # is the same as
+  #   path0 / path1 / ... / pathN
   def join(*args)
     args.unshift self
     result = Path.new(args.pop)
@@ -107,8 +163,8 @@ class Path
   #
   # ArgumentError is raised when it cannot find a relative path.
   def relative_path_from(base_directory)
-    dest_directory = cleanpath.to_s
-    base_directory = Path.new(base_directory).cleanpath.to_s
+    dest_directory = clean.path
+    base_directory = Path.new(base_directory).clean.path
     dest_prefix = dest_directory
     dest_names = []
     while r = chop_basename(dest_prefix)
@@ -148,12 +204,12 @@ class Path
 
     # remove the leading . of +ext+ if present.
     def pure_ext(ext)
-      ext.start_with?('.') ? ext[1..-1] : ext
+      ext = ext.to_s and ext.start_with?('.') ? ext[1..-1] : ext
     end
 
     # add a leading . to +ext+ if missing. Returns '' if +ext+ is empty.
     def dotted_ext(ext)
-      (ext.empty? or ext.start_with?('.')) ? ext : ".#{ext}"
+      ext = ext.to_s and (ext.empty? or ext.start_with?('.')) ? ext : ".#{ext}"
     end
   end
 

data/lib/epath/io.rb

@@ -14,20 +14,22 @@ class Path
   end
   alias :lines :each_line
 
-  # Returns all data from the file, or the first +N+ bytes if specified.
+  # Returns all data from the file, or the first +bytes+ bytes if specified.
   # See +IO.read+.
   def read(*args)
     IO.read(@path, *args)
   end
 
-  # Returns all the bytes from the file, or the first +N+ if specified.
-  # See +IO.binread+.
   if IO.respond_to? :binread
+    # Returns all the bytes from the file, or the first +N+ if specified.
+    # See +IO.binread+.
     def binread(*args)
       IO.binread(@path, *args)
     end
   else
-    alias :binread :read
+    def binread(*args)
+      open('rb', &:read)
+    end
   end
 
   # Returns all the lines from the file. See +IO.readlines+.
@@ -51,6 +53,17 @@ class Path
     end
   end
 
+  if IO.respond_to? :binwrite
+    # Writes +contents+ to +self+. See +IO.binwrite+.
+    def binwrite(contents, *open_args)
+      IO.binwrite(@path, contents, *open_args)
+    end
+  else
+    def binwrite(contents, *open_args)
+      open('wb', *open_args) { |f| f.write(contents) }
+    end
+  end
+
   if IO.respond_to? :write and !RUBY_DESCRIPTION.start_with?('jruby')
     # Appends +contents+ to +self+. See +IO.write+ or +IO#write+.
     def append(contents, open_args = {})
@@ -62,4 +75,20 @@ class Path
       open('a', *open_args) { |f| f.write(contents) }
     end
   end
+
+  # Returns the first +bytes+ bytes of the file.
+  # If the file size is smaller than +bytes+, return the whole contents.
+  def head(bytes)
+    read(bytes)
+  end
+
+  # Returns the last +bytes+ bytes of the file.
+  # If the file size is smaller than +bytes+, return the whole contents.
+  def tail(bytes)
+    return read if size < bytes
+    open { |f|
+      f.seek(-bytes, IO::SEEK_END)
+      f.read
+    }
+  end
 end

data/lib/epath/parts.rb

@@ -44,7 +44,7 @@ class Path
   #
   #   Path('file').add_extension('txt') # => #<Path file.txt>
   def add_extension(ext)
-    return self if ext.empty?
+    return self if ext.to_s.empty?
     Path.new @path+dotted_ext(ext)
   end
   alias :add_ext :add_extension
@@ -64,7 +64,7 @@ class Path
   #
   #   Path('main.c++').replace_extension('cc') # => #<Path main.cc>
   def replace_extension(ext)
-    return without_extension if ext.empty?
+    return without_extension if ext.to_s.empty?
     Path.new(@path[0..-extname.size-1] << dotted_ext(ext))
   end
   alias :sub_ext :replace_extension

data/lib/epath/require_tree.rb

@@ -17,6 +17,6 @@ class Path
   # It is not a real private method because {Path.require_tree}
   # (so the {Path} class) needs to be able to call it.
   def require_tree(source = nil)
-    glob('**/*.rb').sort.each { |file| require file.expand(dir).to_s unless file == source }
+    glob('**/*.rb').sort.each { |file| require file.expand(dir).path unless file == source }
   end
 end

data/lib/epath/version.rb

@@ -1,5 +1,5 @@
 class Path
   # The version of the gem.
   # Set here to avoid duplication and allow introspection.
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epath
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-01 00:00:00.000000000 Z
+date: 2012-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec