rubypath 0.1.0

data/lib/rubypath/file_operations.rb

@@ -0,0 +1,164 @@
+class Path
+  # @!group File Operations
+
+  # Return base name without path.
+  #
+  # @return [String] Base name.
+  #
+  def name
+    ::File.basename internal_path
+  end
+  alias_method :basename, :name
+
+  # Create new file at pointed location or update modification time if file
+  # exists.
+  #
+  # @example
+  #   Path('/path/to/file.txt').touch
+  #   #=> <Path:"/path/to/file.txt">
+  #
+  # @return [Path] Path to touched file.
+  #
+  def touch(*args)
+    with_path(*args) do |path|
+      invoke_backend :touch, path
+      Path path
+    end
+  end
+
+  # Create a file at pointed location and all missing parent directories.
+  #
+  # Given arguments will be joined with current path before directories and
+  # file is created.
+  #
+  # If file already exists nothing will be done.
+  #
+  # @example
+  #   Path('/path/to/file.txt').mkfile
+  #   #=> <Path:"/path/to/file.txt">
+  #
+  # @example
+  #   Path('/').mkfile('path', 'to', 'file.txt')
+  #   #=> <Path:"/path/to/file.txt">
+  #
+  # @return [Path] Path to created or existent file.
+  #
+  def mkfile(*args)
+    with_path(*args) do |path|
+      if !path.exists? && path.parent && !path.parent.exists?
+        path.parent.mkpath
+      end
+
+      if path.exists?
+        raise Errno::ENOENT.new path.to_s unless path.file?
+      else
+        path.touch
+      end
+    end
+  end
+
+  # Search for a file in current directory or parent directories.
+  #
+  # Given search pattern can either be a regular expression or a shell glob
+  # expression.
+  #
+  # @example
+  #   Path.cwd.lookup('project.{yml,yaml}')
+  #   #=> <Path:"/path/config.yml">
+  #
+  # @example
+  #   Path.cwd.lookup(/config(_\d+).ya?ml/)
+  #   #=> <Path:"/path/config_354.yaml">
+  #
+  # @example
+  #   Path('~').lookup('*config', ::File::FNM_DOTMATCH)
+  #   #=> <Path:"/gome/user/.gitconfig">
+  #
+  # @param pattern [String|RegExp] Expression file name must match.
+  # @param flags [Integer] Additional flags. See {::File.fnmatch}.
+  #   Defaults to `File::FNM_EXTGLOB`.
+  # @return [Path] Path to found file or nil.
+  #
+  def lookup(pattern, flags = ::File::FNM_EXTGLOB)
+    expand.ascend do |path|
+      case pattern
+        when String
+          path.entries.each do |c|
+            return path.join(c) if ::File.fnmatch?(pattern, c.name, flags)
+          end
+        when Regexp
+          path.entries.each do |c|
+            return path.join(c) if pattern =~ c.name
+          end
+      end
+    end
+
+    nil
+  end
+
+  # Return file modification time.
+  #
+  # @return [Time] Time of last modification.
+  #
+  def mtime
+    invoke_backend :mtime
+  end
+
+  # Set last modification time.
+  #
+  # @param [Time] Time of last modification.
+  #
+  def mtime=(time)
+    invoke_backend :mtime=, internal_path, time
+  end
+
+  # Return file access time.
+  #
+  # @return [Time] Time of last access.
+  #
+  def atime
+    invoke_backend :atime
+  end
+
+  # Set last access time.
+  #
+  # @param [Time] Time of last access.
+  #
+  def atime=(time)
+    invoke_backend :atime=, internal_path, time
+  end
+
+  def mode
+    invoke_backend :mode
+  end
+
+  def chmod(mode)
+    invoke_backend :chmod, internal_path, mode
+  end
+
+  class << self
+
+    # Read or set process umask.
+    #
+    # @overload umask
+    #   Read process umask.
+    #
+    #   @return [Integer] Process umask.
+    #
+    # @overload umask(mask)
+    #   Set process umask.
+    #
+    #   @param mask [Integer] New process umask.
+    #
+    # @see File.umask
+    #
+    def umask(mask = nil)
+      if mask
+        invoke_backend :set_umask, mask
+      else
+        invoke_backend :get_umask
+      end
+    end
+    alias_method :umask=, :umask
+  end
+end

data/lib/rubypath/file_predicates.rb

@@ -0,0 +1,32 @@
+class Path
+  # @!group File Predicates
+
+  # Check if path points to file.
+  #
+  # @return [Boolean] True if path is a file.
+  # @see ::File.file?
+  #
+  def file?
+    invoke_backend :file?
+  end
+
+  # Check if path points to an existing location.
+  #
+  # @return [Boolean] True if path exists.
+  # @see ::File.exists?
+  #
+  def exists?
+    invoke_backend :exists?
+  end
+  alias_method :exist?, :exists?
+  alias_method :existent?, :exists?
+
+  # Check if path points to a directory.
+  #
+  # @return [Boolean] True if path is a directory.
+  # @see ::File.directory?
+  #
+  def directory?
+    invoke_backend :directory?
+  end
+end

data/lib/rubypath/identity.rb

@@ -0,0 +1,59 @@
+class Path
+  # @!group Identity
+
+  # Return path as string. String will be duped before it gets returned and
+  # cannot be used to modify the path object.
+  #
+  # @return [String] Path as string.
+  def path
+    internal_path.dup
+  end
+  alias_method :to_path, :path
+  alias_method :to_str, :path
+  alias_method :to_s, :path
+
+  # Return a useful object string representation.
+  #
+  # @return [String] Useful object representation
+  def inspect
+    "<#{self.class.name}:#{internal_path}>"
+  end
+
+
+
+  protected
+
+  # Return internal path object without duping.
+  #
+  # Must not be modified to not change internal state.
+  #
+  # @return [String] Internal path.
+  # @see #path
+  #
+  def internal_path
+    @path
+  end
+
+  # If arguments are provided the current path will be joined with given
+  # arguments to the result will be yielded. If no arguments are given the
+  # current path will be yielded.
+  #
+  # Internal helper method.
+  #
+  # @example
+  #   def handle_both(*args)
+  #     with_path(*args) do |path|
+  #       # do something
+  #     end
+  #   end
+  #
+  # Returns whatever the block returns.
+  #
+  def with_path(*args)
+    if args.any?
+      yield join(*args)
+    else
+      yield self
+    end
+  end
+end

data/lib/rubypath/io_operations.rb

@@ -0,0 +1,82 @@
+class Path
+  # @!group IO Operations
+
+  # Write given content to file.
+  #
+  # @overload write(content, [..])
+  #   Write given content to file. An existing file will be truncated otherwise
+  #   a file will be created.
+  #
+  #   Additional arguments will be passed to {::IO.write}.
+  #
+  #   @example
+  #     Path('/path/to/file.txt').write('CONTENT')
+  #     #=> 7
+  #
+  #   @param content [String] Content to write to file.
+  #
+  # @overload write(content, offset, [..])
+  #   Write content at specific position in file. Content will be replaced
+  #   starting at given offset.
+  #
+  #   Additional arguments will be passed to {::IO.write}.
+  #
+  #   @example
+  #     path.write('CONTENT', 4)
+  #     #=> 7
+  #     path.read
+  #     #=> "1234CONTENT2345678"
+  #
+  #   @param content [String] Content to write to file.
+  #   @param offset [Integer] Offset where to start writing. If nil file will
+  #     be truncated.
+  #
+  # @see IO.write
+  # @return [Path] Self.
+  #
+  def write(content, *args)
+    invoke_backend :write, self, content, *args
+    self
+  end
+
+  # Read file content from disk.
+  #
+  # @overload read([..])
+  #   Read all content from file.
+  #
+  #   Additional arguments will be passed to {::IO.read}.
+  #
+  #   @example
+  #     Path('file.txt').read
+  #     #=> "CONTENT"
+  #
+  # @overload read(length, [..])
+  #   Read given amount of bytes from file.
+  #
+  #   Additional arguments will be passed to {::IO.read}.
+  #
+  #   @example
+  #     Path('file.txt').read(4)
+  #     #=> "CONT"
+  #
+  #   @param length [Integer] Number of bytes to read.
+  #
+  # @overload read(length, offset, [..])
+  #   Read given amount of bytes from file starting at given offset.
+  #
+  #   Additional arguments will be passed to {::IO.read}.
+  #
+  #   @example
+  #     Path('file.txt').read(4, 2)
+  #     #=> "NTEN"
+  #
+  #   @param length [Integer] Number of bytes to read.
+  #   @param offset [Integer] Where to start reading.
+  #
+  # @see IO.read
+  # @return [String] Read content.
+  #
+  def read(*args)
+    invoke_backend :read, self, *args
+  end
+end

data/lib/rubypath/mock.rb

@@ -0,0 +1,42 @@
+class Path
+  class << self
+    # @!group Mocking / Virtual File System
+
+    # Configure current path backend. Can be used to configure specified
+    # test scenario. If no virtual or scoped path backend is set the default
+    # one will be used.
+    #
+    # Do not forget to use mock file system in your specs:
+    # See more {Backend.mock}.
+    #
+    #     around do |example|
+    #       Path::Backend.mock &example
+    #     end
+    #
+    # *Note*: Not all operations are supported.
+    #
+    # @example
+    #   Path.mock do |root|
+    #     root.mkpath '/a/b/c/d/e'
+    #     root.touch '/a/b/test.txt'
+    #     root.join('/a/c/lorem.yaml').write YAML.dump({'lorem' => 'ipsum'})
+    #     #...
+    #   end
+    #
+    # @example Configure backend (only with virtual file system)
+    #   Path.mock do |root, backend|
+    #     backend.current_user = 'test'
+    #     backend.homes = {'test' => '/path/to/test/home'}
+    #     #...
+    #   end
+    #
+    # @yield |root, backend| Yield file system root path and current backend.
+    # @yieldparam root [Path] Root path of current packend.
+    # @yieldparam backend [Backend] Current backend.
+    #
+    def mock(opts = {})
+      yield Path('/'), Backend.instance.backend if block_given?
+      nil
+    end
+  end
+end

data/lib/rubypath/path_operations.rb

@@ -0,0 +1,253 @@
+class Path
+  # @!group Path Operations
+
+  # Join path with given arguments.
+  #
+  # @overload initialize([[Path, String, #to_path, #path, #to_s], ...]
+  #   Join all given arguments to build a new path.
+  #
+  #   @example
+  #     Path('/').join('test', %w(a b), 5, Pathname.new('file'))
+  #     # => <Path:"/test/a/b/5/file">
+  #
+  # @return [Path]
+  #
+  def join(*args)
+    parts = args.flatten
+    case parts.size
+      when 0
+        self
+      when 1
+        join = Path parts.shift
+        join.absolute? ? join : Path(::File.join(path, join.path))
+      else
+        join(parts.shift).join(*parts)
+    end
+  end
+
+  # Iterate over all path components.
+  #
+  # @overload each_component
+  #   Return a enumerator to iterate over all path components.
+  #
+  #   @example Iterate over path components using a enumerator
+  #     enum = Path('/path/to/file.txt').each_component
+  #     enum.each{|fn| puts fn}
+  #     # => "path"
+  #     # => "to"
+  #     # => "file.txt"
+  #
+  #   @example Map each path component and create a new path
+  #     path = Path('/path/to/file.txt')
+  #     Path path.each_component.map{|fn| fn.length}
+  #     # => <Path:"/4/2/8">
+  #
+  #   @return [Enumerator] Return a enumerator for all path components.
+  #
+  # @overload each_component(&block)
+  #   Yield given block for each path components.
+  #
+  #   @example Print each file name
+  #     Path('/path/to/file.txt').each_component{|fn| puts fn}
+  #     # => "path"
+  #     # => "to"
+  #     # => "file.txt"
+  #
+  #   @param block [Proc] Block to invoke with each path component.
+  #     If no block is given an enumerator will returned.
+  #   @return [self] Self.
+  #
+  def each_component(opts = {}, &block)
+    rv = if opts[:empty]
+           # split eats leading slashes
+           ary = path.split(Path.separator)
+           # so add an empty string if path ends with slash
+           ary << '' if path[-1] == Path.separator
+           ary.each(&block)
+         else
+           Pathname(path).each_filename(&block)
+         end
+    block ? self : rv
+  end
+
+  # Return an array with all path components.
+  #
+  # @example
+  #   Path('path/to/file').components
+  #   # => ["path", "to", "file"]
+  #
+  # @example
+  #   Path('/path/to/file').components
+  #   # => ["path", "to", "file"]
+  #
+  # @return [Array<String>] File names.
+  #
+  def components
+    each_component.to_a
+  end
+
+  # Converts a pathname to an absolute pathname. Given arguments will be
+  # joined to current path before expanding path. Relative paths are referenced
+  # from the current working directory of the process unless the `:base` option
+  # is set, which will be used as the starting point.
+  #
+  # The given pathname may start with a "~", which expands to the process
+  # owner's home directory (the environment variable HOME must be set
+  # correctly). "~user" expands to the named user's home directory.
+  #
+  # @example
+  #   Path('path/to/../tmp').expand
+  #   #=> <Path:"path/tmp">
+  #
+  # @example
+  #   Path('~/tmp').expand
+  #   #=> <Path:"/home/user/tmp">
+  #
+  # @example
+  #   Path('~oma/tmp').expand
+  #   #=> <Path:"/home/oma/tmp">
+  #
+  # @example
+  #   Path('~/tmp').expand('../file.txt')
+  #   #=> <Path:"/home/user/file.txt">
+  #
+  # @return [Path] Expanded path.
+  # @see ::File#expand_path
+  #
+  def expand(*args)
+    opts = args.last.is_a?(Hash) ? args.pop : {}
+
+    with_path(*args) do |path|
+      base          = Path.like_path(opts[:base] || Backend.instance.getwd)
+      expanded_path = Backend.instance.expand_path(path, base)
+      if expanded_path != internal_path
+        Path expanded_path
+      else
+        self
+      end
+    end
+  end
+
+  alias_method :expand_path, :expand
+  alias_method :absolute, :expand
+  alias_method :absolute_path, :expand
+
+  # Check if path consists of only a filename.
+  #
+  # @example
+  #   Path('file.txt').only_filename?
+  #   #=> true
+  #
+  # @return [Boolean] True if path consists of only a filename.
+  #
+  def only_filename?
+    internal_path.index(Path.separator).nil?
+  end
+
+  # Return path to parent directory. If path is already an absolute or relative
+  # root nil will be returned.
+  #
+  # @example Get parent directory:
+  #   Path.new('/path/to/file').dir.path
+  #   #=> '/path/to'
+  #
+  # @example Try to get parent of absolute root:
+  #   Path.new('/').dir
+  #   #=> nil
+  #
+  # @example Try to get parent of relative root:
+  #   Path.new('.').dir
+  #   #=> nil
+  #
+  # @return [Path] Parent path or nil if path already points to an absolute
+  #   or relative root.
+  #
+  def dirname
+    return nil if %w(. /).include? internal_path
+
+    dir = ::File.dirname internal_path
+    dir.empty? ? nil : self.class.new(dir)
+  end
+
+  alias_method :parent, :dirname
+
+  # Yield given block for path and each ancestor.
+  #
+  # @example
+  #   Path('/path/to/file.txt').ascend{|path| p path}
+  #   #<Path:/path/to/file.txt>
+  #   #<Path:/path/to>
+  #   #<Path:/path>
+  #   #<Path:/>
+  #   #=> <Path:/path/to/file.txt>
+  #
+  # @example
+  #   Path('path/to/file.txt').ascend{|path| p path}
+  #   #<Path:path/to/file.txt>
+  #   #<Path:path/to>
+  #   #<Path:path>
+  #   #<Path:.>
+  #   #=> <Path:path/to/file.txt>
+  #
+  # @yield |path| Yield path and ancestors.
+  # @yieldparam path [Path] Path or ancestor.
+  # @return [Path] Self.
+  #
+  def ascend
+    return to_enum(:ascend) unless block_given?
+
+    path = self
+    loop do
+      yield path
+      break unless (path = path.parent)
+    end
+
+    self
+  end
+
+  alias_method :each_ancestors, :ascend
+
+  # Return an array of all ancestors.
+  #
+  # @example
+  #   Path('/path/to/file').ancestors
+  #   # => [<Path:/path/to/file.txt>, <Path:/path/to>, <Path:/path>, <Path:/>]
+  #
+  # @return [Array<Path>] All ancestors.
+  #
+  def ancestors
+    each_ancestors.to_a
+  end
+
+  # Return given path as a relative path by just striping leading slashes.
+  #
+  # @example
+  #   Path.new('/path/to/file').as_relative
+  #   #=> <Path 'path/to/file'>
+  #
+  # @return [Path] Path transformed to relative path.
+  #
+  def as_relative
+    if (rel_path = internal_path.gsub(/^\/+/, '')) != internal_path
+      Path rel_path
+    else
+      self
+    end
+  end
+
+  # Return given path as a absolute path by just prepending a leading slash.
+  #
+  # @example
+  #   Path.new('path/to/file').as_absolute
+  #   #=> <Path '/path/to/file'>
+  #
+  # @return [Path] Path transformed to absolute path.
+  #
+  def as_absolute
+    if internal_path[0] != '/'
+      Path "/#{internal_path}"
+    else
+      self
+    end
+  end
+end

data/lib/rubypath/path_predicates.rb

@@ -0,0 +1,61 @@
+class Path
+  # @!group Path Predicates
+
+  # Check if path is an absolute path.
+  #
+  # An absolute path is a path with a leading slash.
+  #
+  # @return [Boolean] True if path is absolute.
+  # @see #relative?
+  #
+  def absolute?
+    internal_path[0] == '/'
+  end
+
+  # Check if path is a relative path.
+  #
+  # A relative path does not start with a slash.
+  #
+  # @return [Boolean] True if path is relative.
+  # @see #absolute?
+  #
+  def relative?
+    !absolute?
+  end
+
+  # @overload mountpoint?([Path, String], ...)
+  #   Join current and given paths and check if resulting
+  #   path points to a mountpoint.
+  #
+  #   @example
+  #     Path('/').mountpoint?('tmp')
+  #     #=> true
+  #
+  # @overload mountpoint?
+  #   Check if current path is a mountpoint.
+  #
+  #   @example
+  #     Path('/tmp').mountpoint?
+  #     #=> true
+  #
+  # @return [Boolean] True if path is a mountpoint, false otherwise.
+  # @see Pathname#mountpoint?
+  #
+  def mountpoint?(*args)
+    with_path(*args) do |path|
+      Backend.instance.mountpoint? path
+    end
+  end
+
+  # Check if file or directory is a dot file.
+  #
+  # @example
+  #   Path("~/.gitconfig").dotfile?
+  #   #=> true
+  #
+  # @return [Boolean] True if file is a dot file otherwise false.
+  #
+  def dotfile?
+    name[0] == '.'
+  end
+end

data/lib/rubypath/version.rb

@@ -0,0 +1,11 @@
+class Path
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    STAGE = nil
+    STRING = [MAJOR, MINOR, PATCH, STAGE].reject(&:nil?).join('.').freeze
+
+    def self.to_s; STRING end
+  end
+end