class Pathutil

Constants

VERSION

Attributes

encoding [W]

Public Class Methods

cwd ()

Alias for: pwd

encoding ()

Source

# File lib/pathutil.rb, line 743
def encoding
  return @encoding ||= begin
    Encoding.default_external
  end
end

– @note you are encouraged to override this if you need to. Aliases the default system encoding to us so that we can do most read and write operations with that encoding, instead of being crazy. –

gcwd ()

Alias for: pwd

new (path)

Source

# File lib/pathutil.rb, line 19
def initialize(path)
  return @path = path if path.is_a?(String)
  return @path = path.to_path if path.respond_to?(:to_path)
  return @path = path.to_s
end

– @note A lot of this class can be compatible with Pathname. Initialize a new instance. @return Pathutil –

normalize ()

Source

# File lib/pathutil.rb, line 753
def normalize
  return @normalize ||= {
    :read  => Gem.win_platform?,
    :write => Gem.win_platform?
  }
end

– Normalize CRLF -> LF on Windows reads, to ease your troubles. Normalize LF -> CLRF on Windows write, to ease your troubles. –

pwd ()

Source

# File lib/pathutil.rb, line 729
def pwd
  new(
    Dir.pwd
  )
end

– @note We do nothing special here. Get the current directory that Ruby knows about. @return Pathutil –

Also aliased as: gcwd, cwd

tmpdir (*args)

Source

# File lib/pathutil.rb, line 766
def tmpdir(*args)
  rtn = new(make_tmpname(*args)).tap(&:mkdir)
  ObjectSpace.define_finalizer(rtn, proc do
    rtn.rm_rf
  end)

  rtn
end

– Make a temporary directory. @note if you adruptly exit it will not remove the dir. @note this directory is removed on exit. @return Pathutil –

tmpfile (*args)

Source

# File lib/pathutil.rb, line 781
def tmpfile(*args)
  rtn = new(make_tmpname(*args)).tap(&:touch)
  ObjectSpace.define_finalizer(rtn, proc do
    rtn.rm_rf
  end)

  rtn
end

– Make a temporary file. @note if you adruptly exit it will not remove the dir. @note this file is removed on exit. @return Pathutil –

Public Instance Methods

< (other)

Source

# File lib/pathutil.rb, line 173
def <(other)
  mine, other = expanded_paths(other)
  return false if other == mine
  other.in_path?(mine)
end

– @example Pathutil.new(“/”) < Pathutil.new(“/hello”) # => true Strictly check to see if a path is behind other path but within it. @return true|false –

<= (other)

Source

# File lib/pathutil.rb, line 185
def <=(other)
  mine, other = expanded_paths(other)
  return true if other == mine
  other.in_path?(mine)
end

– Check to see if a path is behind the other path but within it. @example Pathutil.new(“/hello”) < Pathutil.new(“/hello”) # => true @example Pathutil.new(“/”) < Pathutil.new(“/hello”) # => true @return true|false –

=== (other)

Source

# File lib/pathutil.rb, line 141
def ===(other)
  other.is_a?(self.class) && @path == other
end

– @see ‘String#==` for more details. A stricter version of `==` that also makes sure the object matches. @return true|false –

> (other)

Source

# File lib/pathutil.rb, line 162
def >(other)
  mine, other = expanded_paths(other)
  return false if other == mine
  mine.in_path?(other)
end

– @example Pathutil.new(“/hello/world”) > Pathutil.new(“/hello”) # => true Strictly checks to see if a path is deeper but within the path of the other. @return true|false –

>= (other)

Source

# File lib/pathutil.rb, line 151
def >=(other)
  mine, other = expanded_paths(other)
  return true if other == mine
  mine.in_path?(other)
end

– @example Pathutil.new(“/hello”) >= Pathutil.new(“/”) # => true @example Pathutil.new(“/hello”) >= Pathutil.new(“/hello”) # => true Checks to see if a path falls within a path and deeper or is the other. @return true|false –

absolute ()

Source

# File lib/pathutil.rb, line 40
def absolute
  return self if absolute?
  self.class.new("/").join(
    @path
  )
end

– Make a path absolute –

absolute? ()

Source

# File lib/pathutil.rb, line 196
def absolute?
  return !!(
    @path =~ %r!\A(?:[A-Za-z]:)?(?:\\+|/+)!
  )
end

– @note “./” is considered relative. Check to see if the path is absolute, as in: starts with “/” @return true|false –

aggressive_cleanpath ()

Source

# File lib/pathutil.rb, line 615
def aggressive_cleanpath
  return self.class.new("/") if root?

  _out = split_path.each_with_object([]) do |part, out|
    next if part == "." || (part == ".." && out.last == "")
    if part == ".." && out.last && out.last != ".."
      out.pop

    else
      out.push(
        part
      )
    end
  end

  # --

  return self.class.new("/") if _out == [""].freeze
  return self.class.new(".") if _out.empty? && (end_with?(".") || relative?)
  self.class.new(_out.join("/"))
end

– rubocop:disable Metrics/AbcSize rubocop:disable Metrics/CyclomaticComplexity rubocop:disable Metrics/PerceivedComplexity –

Also aliased as: cleanpath_aggressive

ascend () { |path = self| ... }

Source

# File lib/pathutil.rb, line 209
def ascend
  unless block_given?
    return to_enum(
      __method__
    )
  end

  yield(
    path = self
  )

  while (new_path = path.dirname)
    if path == new_path || new_path == "."
      break
    else
      path = new_path
      yield  new_path
    end
  end

  nil
end

– @yield Pathutil Break apart the path and yield each with the previous parts. @example Pathutil.new(“/hello/world”).ascend.to_a # => [“/”, “/hello”, “/hello/world”] @example Pathutil.new(“/hello/world”).ascend { |path| $stdout.puts path } @return Enum –

binread (*args, **kwd)

Source

# File lib/pathutil.rb, line 516
def binread(*args, **kwd)
  kwd[:encoding] ||= encoding

  if normalize[:read]
    File.binread(self, *args, kwd).encode({
      :universal_newline => true
    })

  else
    File.read(
      self, *args, kwd
    )
  end
end

– @note You can set the default encodings via the class. Binread took two steroid shots: it can normalize your string, and encode. @return String –

binwrite (data, *args, **kwd)

Source

# File lib/pathutil.rb, line 576
def binwrite(data, *args, **kwd)
  kwd[:encoding] ||= encoding

  if normalize[:write]
    File.binwrite(self, data.encode(
      :crlf_newline => true
    ), *args, kwd)

  else
    File.binwrite(
      self, data, *args, kwd
    )
  end
end

– @note You can set the default encodings via the class. Binwrite took two steroid shots: it can normalize your string, and encode. @return Fixnum<Bytes> –

chdir () { || ... }

Source

# File lib/pathutil.rb, line 358
def chdir
  if !block_given?
    Dir.chdir(
      @path
    )

  else
    Dir.chdir @path do
      yield
    end
  end
end

– @yield &block Move to the current directory temporarily (or for good) and do work son. @note you do not need to ship a block at all. @return nil –

children () { |path| ... }

Source

# File lib/pathutil.rb, line 310
def children
  ary = []

  Dir.foreach(@path) do |path|
    if path == "." || path == ".."
      next
    else
      path = self.class.new(File.join(@path, path))
      yield path if block_given?
      ary.push(
        path
      )
    end
  end

  ary
end

– @return Array<Pathutil> Grab all of the children from the current directory, including hidden. @yield Pathutil –

Also aliased as: entries

cleanpath (symlink = false)

Source

# File lib/pathutil.rb, line 52
def cleanpath(symlink = false)
  symlink ? conservative_cleanpath : aggressive_cleanpath
end

– @see Pathname#cleanpath. @note This is a wholesale rip and cleanup of Pathname#cleanpath @return Pathutil –

conservative_cleanpath ()

Source

# File lib/pathutil.rb, line 639
def conservative_cleanpath
  _out = split_path.each_with_object([]) do |part, out|
    next if part == "." || (part == ".." && out.last == "")
    out.push(
      part
    )
  end

  # --

  if !_out.empty? && basename == "." && _out.last != "" && _out.last != ".."
    _out << "."
  end

  # --

  return self.class.new("/") if _out == [""].freeze
  return self.class.new(".") if _out.empty? && (end_with?(".") || relative?)
  return self.class.new(_out.join("/")).join("") if @path =~ %r!/\z! \
    && _out.last != "." && _out.last != ".."
  self.class.new(_out.join("/"))
end

–

Also aliased as: cleanpath_conservative

descend () { |val| ... }

Source

# File lib/pathutil.rb, line 239
def descend
  unless block_given?
    return to_enum(
      __method__
    )
  end

  ascend.to_a.reverse_each do |val|
    yield val
  end

  nil
end

– @yield Pathutil Break apart the path in reverse order and descend into the path. @example Pathutil.new(“/hello/world”).descend.to_a # => [“/hello/world”, “/hello”, “/”] @example Pathutil.new(“/hello/world”).descend { |path| $stdout.puts path } @return Enum –

each_filename () { |file| ... }

Source

# File lib/pathutil.rb, line 388
def each_filename
  return to_enum(__method__) unless block_given?
  @path.split(File::SEPARATOR).delete_if(&:empty?).each do |file|
    yield file
  end
end

– @yield Pathutil Splits the path returning each part (filename) back to you. @return Enum –

each_line () { |line| ... }

Source

# File lib/pathutil.rb, line 259
def each_line
  return to_enum(__method__) unless block_given?
  readlines.each do |line|
    yield line
  end

  nil
end

– @yield Pathutil @example Pathutil.new(“/hello/world”).each_line { |line| $stdout.puts line } Wraps ‘readlines` and allows you to yield on the result. @return Enum –

encoding ()

Source

# File lib/pathutil.rb, line 485
def encoding
  return @encoding ||= begin
    self.class.encoding
  end
end

– @see ‘self.class.encoding` as this is an alias. –

enforce_root (root)

Source

# File lib/pathutil.rb, line 443
def enforce_root(root)
  return self if !relative? && in_path?(root)
  self.class.new(root).join(
    self
  )
end

– Expands the path and left joins the root to the path. @return Pathutil –

Also aliased as: prepend

find () { |class.new(val)| ... }

Source

# File lib/pathutil.rb, line 376
def find
  return to_enum(__method__) unless block_given?
  Find.find @path do |val|
    yield self.class.new(val)
  end
end

– @yield Pathutil Find all files without care and yield the given block. @return Enum –

fnmatch? (matcher)

Source

# File lib/pathutil.rb, line 275
def fnmatch?(matcher)
  matcher.is_a?(Regexp) ? !!(self =~ matcher) : \
    File.fnmatch(matcher, self)
end

– @example Pathutil.new(“/hello”).fnmatch?(“/hello”) # => true Unlike traditional ‘fnmatch`, with this one `Regexp` is allowed. @example Pathutil.new(“/hello”).fnmatch?(/h/) # => true @see `File#fnmatch` for more information. @return true|false –

Also aliased as: fnmatch

glob (pattern, flags = 0) { |class.new( join| ... }

Source

# File lib/pathutil.rb, line 334
def glob(pattern, flags = 0)
  unless block_given?
    return to_enum(
      __method__, pattern, flags
    )
  end

  chdir do
    Dir.glob(pattern, flags).each do |file|
      yield self.class.new(
        File.join(@path, file)
      )
    end
  end

  nil
end

– @yield Pathutil Allows you to glob however you wish to glob in the current ‘Pathutil` @see `File::Constants` for a list of flags. @return Enum –

in_path? (path)

Source

# File lib/pathutil.rb, line 292
def in_path?(path)
  path = self.class.new(path).expand_path.split_path
  mine = (symlink?? expand_path.realpath : expand_path).split_path
  path.each_with_index { |part, index| return false if mine[index] != part }
  true
end

– Allows you to check if the current path is in the path you want. @return true|false –

inspect ()

Source

# File lib/pathutil.rb, line 301
def inspect
  "#<#{self.class}:#{@path}>"
end

–

normalize ()

Source

# File lib/pathutil.rb, line 476
def normalize
  return @normalize ||= begin
    self.class.normalize
  end
end

– @see ‘self.class.normalize` as this is an alias. –

parent ()

Source

# File lib/pathutil.rb, line 400
def parent
  return self if @path == "/"
  self.class.new(absolute?? File.dirname(@path) : File.join(
    @path, ".."
  ))
end

– Get the parent of the current path. @note This will simply return self if “/”. @return Pathutil –

read (*args, **kwd)

Source

# File lib/pathutil.rb, line 496
def read(*args, **kwd)
  kwd[:encoding] ||= encoding

  if normalize[:read]
    File.read(self, *args, kwd).encode({
      :universal_newline => true
    })

  else
    File.read(
      self, *args, kwd
    )
  end
end

– @note You can set the default encodings via the class. Read took two steroid shots: it can normalize your string, and encode. @return String –

read_json (throw_missing: false)

Source

# File lib/pathutil.rb, line 113
def read_json(throw_missing: false)
  JSON.parse(
    read
  )

rescue Errno::ENOENT
  throw_missing ? raise : (
    return {}
  )
end

– Read the file as a JSON file turning it into an object. @see self.class.read_json as this is a direct alias of that method. @return Hash –

read_yaml (throw_missing: false, **kwd)

Source

# File lib/pathutil.rb, line 97
def read_yaml(throw_missing: false, **kwd)
  self.class.load_yaml(
    read, **kwd
  )

rescue Errno::ENOENT
  throw_missing ? raise : (
    return {}
  )
end

– Read the file as a YAML file turning it into an object. @see self.class.load_yaml as this a direct alias of that method. @return Hash –

readlines (*args, **kwd)

Source

# File lib/pathutil.rb, line 536
def readlines(*args, **kwd)
  kwd[:encoding] ||= encoding

  if normalize[:read]
    File.readlines(self, *args, kwd).encode({
      :universal_newline => true
    })

  else
    File.readlines(
      self, *args, kwd
    )
  end
end

– @note You can set the default encodings via the class. Readlines took two steroid shots: it can normalize your string, and encode. @return Array<String> –

relative ()

Source

# File lib/pathutil.rb, line 29
def relative
  return self if relative?
  self.class.new(strip_windows_drive.gsub(
    %r!\A(\\+|/+)!, ""
  ))
end

– Make a path relative. –

relative_path_from (from)

Source

# File lib/pathutil.rb, line 432
def relative_path_from(from)
  from = self.class.new(from).expand_path.gsub(%r!/$!, "")
  self.class.new(expand_path.gsub(%r!^#{
    from.regexp_escape
  }/!, ""))
end

– A less complex version of ‘relative_path_from` that simply uses a `Regexp` and returns the full path if it cannot be determined. @return Pathutil –

root? ()

Source

# File lib/pathutil.rb, line 284
def root?
  !!(self =~ %r!\A(?:[A-Za-z]:)?(?:\\+|/+)\z!)
end

– Allows you to quickly determine if the file is the root folder. @return true|false –

safe_copy (to, root: nil, ignore: [])

Source

# File lib/pathutil.rb, line 456
def safe_copy(to, root: nil, ignore: [])
  raise ArgumentError, "must give a root" unless root
  root = self.class.new(root)
  to   = self.class.new(to)

  if directory?
    safe_copy_directory(to, {
      :root => root, :ignore => ignore
    })

  else
    safe_copy_file(to, {
      :root => root
    })
  end
end

– Copy a directory, allowing symlinks if the link falls inside of the root. This is indented for people who wish some safety to their copies. @note Ignore is ignored on safe_copy file because it’s explicit. @return nil –

search_backwards (file, backwards: Float::INFINITY) { |file| ... }

Source

# File lib/pathutil.rb, line 63
def search_backwards(file, backwards: Float::INFINITY)
  ary = []

  ascend.with_index(1).each do |path, index|
    if index > backwards
      break

    else
      Dir.chdir path do
        if block_given?
          file = self.class.new(file)
          if yield(file)
            ary.push(
              file
            )
          end

        elsif File.exist?(file)
          ary.push(self.class.new(
            path.join(file)
          ))
        end
      end
    end
  end

  ary
end

– @yield Pathutil @note It will return all results that it finds across all ascending paths. @example Pathutil.new(“~/”).expand_path.search_backwards(“.bashrc”) => [#<Pathutil:/home/user/.bashrc>] Search backwards for a file (like Rakefile, _config.yml, opts.yml). @return Enum –

split ()

Source

# File lib/pathutil.rb, line 412
def split
  File.split(@path).collect! do |path|
    self.class.new(path)
  end
end

– @yield Pathutil Split the file into its dirname and basename, so you can do stuff. @return nil –

split_path ()

Source

# File lib/pathutil.rb, line 130
def split_path
  @path.split(
    %r!\\+|/+!
  )
end

– @note The blank part is intentionally left there so that you can rejoin. Splits the path into all parts so that you can do step by step comparisons @example Pathutil.new(“/my/path”).split_path # => [“”, “my”, “path”] @return Array<String> –

strip_windows_drive (path = @path)

Source

# File lib/pathutil.rb, line 603
def strip_windows_drive(path = @path)
  self.class.new(path.gsub(
    %r!\A[A-Za-z]:(?:\\+|/+)!, ""
  ))
end

– Strips the windows drive from the path. –

sub_ext (ext)

Source

# File lib/pathutil.rb, line 423
def sub_ext(ext)
  self.class.new(@path.chomp(File.extname(@path)) + ext)
end

– @note Your extension should start with “.” Replace a files extension with your given extension. @return Pathutil –

to_regexp (guard: true)

Source

# File lib/pathutil.rb, line 593
def to_regexp(guard: true)
  Regexp.new((guard ? "\\A" : "") + Regexp.escape(
    self
  ))
end

–

write (data, *args, **kwd)

Source

# File lib/pathutil.rb, line 556
def write(data, *args, **kwd)
  kwd[:encoding] ||= encoding

  if normalize[:write]
    File.write(self, data.encode(
      :crlf_newline => true
    ), *args, kwd)

  else
    File.write(
      self, data, *args, kwd
    )
  end
end

– @note You can set the default encodings via the class. Write took two steroid shots: it can normalize your string, and encode. @return Fixnum<Bytes> –

Private Instance Methods

cleanpath_aggressive ()

Alias for: aggressive_cleanpath

cleanpath_conservative ()

Alias for: conservative_cleanpath

entries ()

Alias for: children

expanded_paths (path)

Source

# File lib/pathutil.rb, line 669
def expanded_paths(path)
  return expand_path, self.class.new(path).expand_path
end

– rubocop:enable Metrics/AbcSize rubocop:enable Metrics/CyclomaticComplexity rubocop:enable Metrics/PerceivedComplexity Expand the paths and return. –

fnmatch (matcher)

Alias for: fnmatch?

prepend (root)

Alias for: enforce_root

safe_copy_directory (to, root: nil, ignore: [])

Source

# File lib/pathutil.rb, line 688
def safe_copy_directory(to, root: nil, ignore: [])
  ignore = [ignore].flatten.uniq

  if !in_path?(root)
    raise Errno::EPERM, "#{self} not in #{
      root
    }"

  else
    to.mkdir_p unless to.exist?
    children do |file|
      unless ignore.any? { |path| file.in_path?(path) }
        if !file.in_path?(root)
          raise Errno::EPERM, "#{file} not in #{
            root
          }"

        elsif file.file?
          FileUtils.cp(file, to, {
            :preserve => true
          })

        else
          path = file.realpath
          path.safe_copy(to.join(file.basename), {
            :root => root, :ignore => ignore
          })
        end
      end
    end
  end
end

– Safely copy a directory and it’s sub-files. –

safe_copy_file (to, root: nil)

Source

# File lib/pathutil.rb, line 677
def safe_copy_file(to, root: nil)
  raise Errno::EPERM, "#{self} not in #{root}" unless in_path?(root)
  FileUtils.cp(self, to, {
    :preserve => true
  })
end

– Safely copy a file. –