rubypath 1.0.0 → 1.0.1

data/lib/rubypath/backend/sys.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+class Path
+  class Backend
+    # rubocop:disable ClassLength
+    class Sys
+      def initialize(root = nil)
+        @root  = ::File.expand_path root if root
+        @umask = File.umask
+      end
+
+      def quit
+        File.umask @umask
+      end
+
+      def home(user)
+        ::File.expand_path "~#{user}"
+      end
+
+      def getwd
+        ::Dir.getwd
+      end
+
+      def user
+        require 'etc'
+
+        Etc.getlogin
+      end
+
+      def r(path)
+        return path unless @root
+        ::File.expand_path("#{@root}/#{::File.expand_path(path)}")
+      end
+
+      def ur(path)
+        return path unless @root
+
+        if path.slice(0, @root.length) == @root
+          path.slice(@root.length, path.length - @root.length)
+        else
+          path
+        end
+      end
+
+      def fs(path, obj, method, *args)
+        # puts "[FS] #{obj} #{method} #{args.inspect}"
+        obj.send method, *args
+      rescue Errno::ENOENT
+        raise Errno::ENOENT.new path
+      rescue Errno::EISDIR
+        raise Errno::EISDIR.new path
+      rescue Errno::ENOTDIR
+        raise Errno::ENOTDIR.new path
+      rescue Errno::EACCES
+        raise Errno::EACCES.new path
+      end
+
+      ## OPERATIONS
+
+      def expand_path(path, base)
+        ::File.expand_path path, base
+      end
+
+      def exists?(path)
+        fs path, ::File, :exists?, r(path)
+      end
+
+      def mkdir(path)
+        fs path, ::Dir, :mkdir, r(path)
+      end
+
+      def mkpath(path)
+        fs path, ::FileUtils, :mkdir_p, r(path)
+      end
+
+      def directory?(path)
+        fs path, ::File, :directory?, r(path)
+      end
+
+      def file?(path)
+        fs path, ::File, :file?, r(path)
+      end
+
+      def touch(path)
+        fs path, ::FileUtils, :touch, r(path)
+      end
+
+      def write(path, content, *args)
+        fs path, ::IO, :write, r(path), content, *args
+      end
+
+      def read(path, *args)
+        fs path, ::IO, :read, r(path), *args
+      end
+
+      def mtime(path)
+        fs path, ::File, :mtime, r(path)
+      end
+
+      def mtime=(path, time)
+        fs path, ::File, :utime, atime(path), time, r(path)
+      end
+
+      def atime(path)
+        fs path, ::File, :atime, r(path)
+      end
+
+      def atime=(path, time)
+        fs path, ::File, :utime, time, mtime(path), r(path)
+      end
+
+      def entries(path)
+        fs path, ::Dir, :entries, r(path)
+      end
+
+      def glob(pattern, flags = 0)
+        if block_given?
+          fs pattern, ::Dir, :glob, r(pattern), flags do |path|
+            yield ur(path)
+          end
+        else
+          fs(pattern, ::Dir, :glob, r(pattern), flags).map {|path| ur path }
+        end
+      end
+
+      def umask
+        File.umask
+      end
+
+      def umask=(mask)
+        File.umask mask
+      end
+
+      def mode(path)
+        fs(path, ::File, :stat, r(path)).mode & 0o777
+      end
+
+      def chmod(path, mode)
+        fs path, ::File, :chmod, mode, r(path)
+      end
+
+      def unlink(path)
+        fs path, ::File, :unlink, r(path)
+      end
+
+      def rmtree(path)
+        fs path, ::FileUtils, :rm_r, r(path), force: true
+      end
+
+      def rmtree!(path)
+        fs path, ::FileUtils, :rm_r, r(path)
+      end
+
+      def safe_rmtree(path)
+        fs path, ::FileUtils, :rm_r, r(path), force: true, secure: true
+      end
+
+      def safe_rmtree!(path)
+        fs path, ::FileUtils, :rm_r, r(path), secure: true
+      end
+    end
+  end
+end

data/lib/rubypath/comparison.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class Path
+  # @!group Comparison
+
+  # Compare path to given object. If object is a string, Path or #{Path.like?}
+  # they will be compared using the string paths. Otherwise they are assumed
+  # as not equal.
+  #
+  # @param other [Object] Object to compare path with.
+  # @return [Boolean] True if object represents same path.
+  #
+  def eql?(other)
+    if other.is_a?(Path)
+      cleanpath.internal_path == other.cleanpath.internal_path
+    elsif Path.like?(other)
+      Path.new(other).eql?(self)
+    end
+  end
+  alias == eql?
+end

data/lib/rubypath/construction.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+class Path
+  class << self
+    # @!group Construction
+
+    # Create new {Path}.
+    #
+    # If single argument is a path object it will be returned and no new one
+    # will be created. If not arguments are given {Path::EMPTY} will be
+    # returned.
+    #
+    # @see #initialize
+    #
+    def new(*args)
+      args.flatten!
+      return Path::EMPTY if args.empty?
+      return args.first if args.size == 1 && args.first.is_a?(self)
+      super
+    end
+
+    # Check if given object is like a path.
+    #
+    # An object is like a path if
+    # 1. It is a {Path} object.
+    # 2. It is a string.
+    # 3. It responds to {#to_path} and {#to_path} returns a string.
+    # 4. It responds to {#path} and {#path} returns a string.
+    #
+    # If no rule matches it is not considered to be like a path.
+    #
+    # @return [Boolean] True if object is path like, false otherwise.
+    #
+    # rubocop:disable Metrics/CyclomaticComplexity
+    #
+    def like?(obj)
+      return true if obj.is_a?(self)
+      return true if obj.is_a?(String)
+      return true if obj.respond_to?(:to_path) && obj.to_path.is_a?(String)
+      return true if obj.respond_to?(:path) && obj.path.is_a?(String)
+      false
+    end
+    # rubocop:enable all
+
+    # Convert given object to path string using {::Path.like?} rules.
+    #
+    # @note Should not be used directly.
+    #
+    # @return [String]
+    # @raise [ArgumentError] If given object is not {::Path.like?}.
+    # @see ::Path.like?
+    #
+    # rubocop:disable Metrics/MethodLength
+    def like_path(obj)
+      case obj
+        when String
+          return obj
+        else
+          %i[to_path path to_str to_s].each do |mth|
+            if obj.respond_to?(mth) && obj.send(mth).is_a?(String)
+              return obj.send(mth)
+            end
+          end
+      end
+
+      raise ArgumentError.new \
+        "Argument #{obj.inspect} cannot be converted to path string."
+    end
+    # rubocop:enable all
+
+    # Return system file path separator.
+    #
+    # @return [String] File separator.
+    # @see ::File::SEPARATOR
+    #
+    def separator
+      ::File::SEPARATOR
+    end
+
+    # Allow class object to be used as a bock.
+    #
+    # @example
+    #   %w(path/to/fileA path/to/fileB).map(&Path)
+    #
+    def to_proc
+      proc {|*args| Path.new(*args) }
+    end
+  end
+
+  # @!group Construction
+
+  # Initialize new {Path} object.
+  #
+  # Given arguments will be converted to String using `#to_path`, `#path` or
+  # `#to_s` in this order if they return a String object.
+  #
+  # @overload initialize([[String, #to_path, #path, #to_s], ...]
+  #
+  def initialize(*args)
+    parts = args.flatten
+    @path = if parts.size > 1
+              ::File.join(*parts.map {|p| Path.like_path p })
+            elsif parts.size == 1
+              Path.like_path(parts.first).dup
+            else
+              ''
+            end
+  end
+
+  # Empty path.
+  #
+  # @return [Path] Empty path.
+  #
+  EMPTY = Path.new('')
+end

data/lib/rubypath/dir_operations.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+class Path
+  class << self
+    # Returns the current working directory.
+    #
+    # @return [Path] Current working directory.
+    # @see ::Dir.getwd
+    #
+    def getwd
+      new Backend.instance.getwd
+    end
+
+    def glob(pattern, flags = nil)
+      flags = default_glob_flags(flags)
+
+      if block_given?
+        Backend.instance.glob(pattern, flags) {|path| yield Path path }
+      else
+        Backend.instance.glob(pattern, flags).map(&Path)
+      end
+    end
+
+    # @!visibility private
+    #
+    def default_glob_flags(flags)
+      if flags.nil? && defined?(::File::FNM_EXTGLOB)
+        ::File::FNM_EXTGLOB
+      else
+        flags.to_i
+      end
+    end
+  end
+
+  # @!group Directory Operations
+
+  # Create directory.
+  #
+  # Given arguments will be joined with current path before directory is
+  # created.
+  #
+  # @raise [Errno::ENOENT] If parent directory could not created.
+  # @return [Path] Path to created directory.
+  # @see #mkpath
+  #
+  def mkdir(*args)
+    with_path(*args) do |path|
+      Backend.instance.mkdir path
+      Path path
+    end
+  end
+
+  # Create directory and all missing parent directories.
+  #
+  # Given arguments will be joined with current path before directories
+  # are created.
+  #
+  # @return [Path] Path to created directory.
+  # @see #mkdir
+  # @see ::FileUtils.mkdir_p
+  #
+  def mkpath(*args)
+    with_path(*args) do |path|
+      Backend.instance.mkpath path
+      Path path
+    end
+  end
+  alias mkdir_p mkpath
+
+  # Return list of entries in directory. That includes special directories
+  # (`.`, `..`).
+  #
+  # Given arguments will be joined before children are listed for directory.
+  #
+  # @return [Array<Path>] Entries in directory.
+  #
+  def entries(*_args)
+    invoke_backend(:entries, internal_path).map(&Path)
+  end
+
+  #
+  def glob(pattern, flags = nil, &block)
+    Path.glob(::File.join(escaped_glob_path, pattern), flags, &block)
+  end
+
+  # Removes file or directory. If it's a directory it will be removed
+  # recursively.
+  #
+  # WARNING: This method causes local vulnerability if one of parent
+  # directories or removing directory tree are world writable (including
+  # `/tmp`, whose permission is 1777), and the current process has strong
+  # privilege such as Unix super user (root), and the system has symbolic link.
+  # For secure removing see {#safe_rmtree}.
+  #
+  # @return [Path] Path to removed file or directory.
+  #
+  def rmtree(*args)
+    with_path(*args) do |path|
+      invoke_backend :rmtree, internal_path
+      Path path
+    end
+  end
+  alias rm_rf rmtree
+
+  # Removes file or directory. If it's a directory it will be removed
+  # recursively.
+  #
+  # This method uses #{FileUtils#remove_entry_secure} to avoid TOCTTOU
+  # (time-of-check-to-time-of-use) local security vulnerability of {#rmtree}.
+  # {#rmtree} causes security hole when:
+  #
+  # * Parent directory is world writable (including `/tmp`).
+  # * Removing directory tree includes world writable directory.
+  # * The system has symbolic link.
+  #
+  # @return [Path] Path to removed file or directory.
+  #
+  def safe_rmtree(*args)
+    with_path(*args) do |path|
+      invoke_backend :safe_rmtree, internal_path
+      Path path
+    end
+  end
+
+  # Removes file or directory. If it's a directory it will be removed
+  # recursively.
+  #
+  # This method behaves exactly like {#rmtree} but will raise exceptions
+  # e.g. when file does not exist.
+  #
+  # @return [Path] Path to removed file or directory.
+  #
+  def rmtree!(*args)
+    with_path(*args) do |path|
+      invoke_backend :rmtree!, internal_path
+      Path path
+    end
+  end
+  alias rm_r rmtree!
+
+  # Removes file or directory. If it's a directory it will be removed
+  # recursively.
+  #
+  # This method behaves exactly like {#safe_rmtree} but will raise exceptions
+  # e.g. when file does not exist.
+  #
+  # @return [Path] Path to removed file or directory.
+  #
+  def safe_rmtree!(*args)
+    with_path(*args) do |path|
+      invoke_backend :safe_rmtree!, internal_path
+      Path path
+    end
+  end
+
+  private
+
+  def escaped_glob_path
+    internal_path.gsub(/[\[\]\*\?\{\}]/, '\\\\\0')
+  end
+end