Pathname (Class)

In: pathname.rb
Parent: Object

Dir

Methods

+   <=>   ==   ===   absolute?   atime   basename   blockdev?   chardev?   chdir   children   chmod   chown   chroot   cleanpath   ctime   dir_foreach   directory?   dirname   each_entry   each_filename   each_line   entries   eql?   executable?   executable_real?   exist?   expand_path   extname   file?   fnmatch   fnmatch?   foreachline   ftype   getwd   glob   grpowned?   hash   inspect   join   lchmod   lchown   link   lstat   make_link   make_symlink   mkdir   mountpoint?   mtime   new   open   opendir   owned?   parent   pipe?   pwd   read   readable?   readable_real?   readlines   readlink   realpath   relative?   relative_path_from   rename   rmdir   root?   setgid?   setuid?   size   size?   socket?   split   stat   sticky?   symlink   symlink?   sysopen   to_s   to_str   truncate   utime   writable?   writable_real?   zero?  

Classes and Modules

Class Pathname::Pathname

Public Class methods

[Source]

# File pathname.rb, line 12
  def initialize(path)
    @path = path.to_str.dup
    @path.freeze

    if /\0/ =~ @path
      raise ArgumentError, "pathname contains \\0: #{@path.inspect}"
    end
  end

[Source]

# File pathname.rb, line 421
  def Pathname.glob(*args)
    if block_given?
      Dir.glob(*args) {|f| yield Pathname.new(f) }
    else
      Dir.glob(*args).map {|f| Pathname.new(f) }
    end
  end

[Source]

# File pathname.rb, line 429
  def Pathname.getwd() Pathname.new(Dir.getwd) end
pwd()

Alias for getwd

Public Instance methods

[Source]

# File pathname.rb, line 21
  def ==(other)
    return false unless Pathname === other
    other.to_s == @path
  end
===(other)

Alias for #==

eql?(other)

Alias for #==

[Source]

# File pathname.rb, line 28
  def <=>(other)
    return nil unless Pathname === other
    @path.tr('/', "\0") <=> other.to_s.tr('/', "\0")
  end

[Source]

# File pathname.rb, line 33
  def hash
    @path.hash
  end

[Source]

# File pathname.rb, line 37
  def to_s
    @path.dup
  end
to_str()

Alias for to_s

[Source]

# File pathname.rb, line 44
  def inspect
    "#<#{self.class}:#{@path}>"
  end

cleanpath returns clean pathname of self which is without consecutive slashes and useless dots.

If true is given as the optional argument consider_symlink, symbolic links are considered. It makes more dots are retained.

cleanpath doesn’t access actual filesystem.

[Source]

# File pathname.rb, line 55
  def cleanpath(consider_symlink=false)
    if consider_symlink
      cleanpath_conservative
    else
      cleanpath_aggressive
    end
  end

realpath returns a real pathname of self in actual filesystem. The real pathname doesn’t contain a symlink and useless dots.

It returns absolute pathname.

[Source]

# File pathname.rb, line 113
  def realpath(*args)
    unless args.empty?
      warn "The argument for Pathname#realpath is obsoleted."
    end
    force_absolute = args.fetch(0, true)

    if %{\A/} =~ @path
      top = '/'
      unresolved = @path.scan(%{[^/]+})
    elsif force_absolute
      # Although POSIX getcwd returns a pathname which contains no symlink,

      # 4.4BSD-Lite2 derived getcwd may return the environment variable $PWD

      # which may contain a symlink.

      # So the return value of Dir.pwd should be examined.

      top = '/'
      unresolved = Dir.pwd.scan(%{[^/]+}) + @path.scan(%{[^/]+})
    else
      top = ''
      unresolved = @path.scan(%{[^/]+})
    end
    resolved = []

    until unresolved.empty?
      case unresolved.last
      when '.'
        unresolved.pop
      when '..'
        resolved.unshift unresolved.pop
      else
        loop_check = {}
        while (stat = File.lstat(path = top + unresolved.join('/'))).symlink?
          symlink_id = "#{stat.dev}:#{stat.ino}"
          raise Errno::ELOOP.new(path) if loop_check[symlink_id]
          loop_check[symlink_id] = true
          if %{\A/} =~ (link = File.readlink(path))
            top = '/'
            unresolved = link.scan(%{[^/]+})
          else
            unresolved[-1,1] = link.scan(%{[^/]+})
          end
        end
        next if (filename = unresolved.pop) == '.'
        if filename != '..' && resolved.first == '..'
          resolved.shift
        else
          resolved.unshift filename
        end
      end
    end

    if top == '/'
      resolved.shift while resolved[0] == '..'
    end
    
    if resolved.empty?
      Pathname.new(top.empty? ? '.' : '/')
    else
      Pathname.new(top + resolved.join('/'))
    end
  end

parent method returns parent directory.

If self is `.’, `..’ is returned. Otherwise, `..’ is joined to self.

[Source]

# File pathname.rb, line 178
  def parent
    if @path == '.'
      Pathname.new('..')
    else
      self.join('..')
    end
  end

mountpoint? method returns true if self points a mountpoint.

[Source]

# File pathname.rb, line 187
  def mountpoint?
    begin
      stat1 = self.lstat
      stat2 = self.parent.lstat
      stat1.dev == stat2.dev && stat1.ino == stat2.ino ||
      stat1.dev != stat2.dev
    rescue Errno::ENOENT
      false
    end
  end

root? method is a predicate for root directory. I.e. it returns true if the pathname consists of consecutive slashes.

It doesn’t access actual filesystem. So it may return false for some pathnames which points root such as "/usr/..".

[Source]

# File pathname.rb, line 204
  def root?
    %{\A/+\z} =~ @path ? true : false
  end

absolute? method is a predicate for absolute pathname. It returns true if self is beginning with a slash.

[Source]

# File pathname.rb, line 210
  def absolute?
    %{\A/} =~ @path ? true : false
  end

relative? method is a predicate for relative pathname. It returns true unless self is beginning with a slash.

[Source]

# File pathname.rb, line 216
  def relative?
    !absolute?
  end

each_filename iterates over self for each filename components.

[Source]

# File pathname.rb, line 221
  def each_filename
    @path.scan(%{[^/]+}) { yield $& }
  end

Pathname#+ return new pathname which is concatenated with self and an argument. If self is the current working directory `.’ or the argument is absolute pathname, the argument is just returned. If the argument is `.’, self is returned.

[Source]

# File pathname.rb, line 231
  def +(other)
    other = Pathname.new(other) unless Pathname === other
    if @path == '.' || other.absolute?
      other
    elsif other.to_s == '.'
      self
    elsif %{/\z} =~ @path
      Pathname.new(@path + other.to_s)
    else
      Pathname.new(@path + '/' + other.to_s)
    end
  end

Pathname#join joins pathnames.

path0.join(path1, … pathN) is same as path0 + path1 + … + pathN.

[Source]

# File pathname.rb, line 247
  def join(*args)
    args.map! {|arg| Pathname === arg ? arg : Pathname.new(arg) }
    args.inject(self) {|pathname, arg| pathname + arg }
  end

Pathname#children returns the children of the directory as an array of pathnames.

By default, the returned pathname can be used to access the corresponding file in the directory. This is because the pathname contains self as a prefix unless self is `.’.

If false is given for the optional argument `with_directory’, just filenames of children is returned. In this case, the returned pathname cannot be used directly to access the corresponding file when self doesn’t point working directory.

Note that the result never contain the entry `.’ and `..’ in the directory because they are not child.

This method is exist since 1.8.1.

[Source]

# File pathname.rb, line 268
  def children(with_directory=true)
    with_directory = false if @path == '.'
    result = []
    Dir.foreach(@path) {|e|
      next if e == '.' || e == '..'
      if with_directory
        result << Pathname.new(File.join(@path, e))
      else
        result << Pathname.new(e)
      end
    }
    result
  end

Pathname#relative_path_from returns a relative path from the argument to self. If self is absolute, the argument must be absolute too. If self is relative, the argument must be relative too.

relative_path_from doesn’t access actual filesystem. It assumes no symlinks.

ArgumentError is raised when it cannot find a relative path.

This method is exist since 1.8.1.

[Source]

# File pathname.rb, line 293
  def relative_path_from(base_directory)
    if self.absolute? != base_directory.absolute?
      raise ArgumentError,
        "relative path between absolute and relative path: #{self.inspect}, #{base_directory.inspect}"
    end

    dest = []
    self.cleanpath.each_filename {|f|
      next if f == '.'
      dest << f
    }

    base = []
    base_directory.cleanpath.each_filename {|f|
      next if f == '.'
      base << f
    }

    while !base.empty? && !dest.empty? && base[0] == dest[0]
      base.shift
      dest.shift
    end

    if base.include? '..'
      raise ArgumentError, "base_directory has ..: #{base_directory.inspect}"
    end

    base.fill '..'
    relpath = base + dest
    if relpath.empty?
      Pathname.new(".")
    else
      Pathname.new(relpath.join('/'))
    end
  end

Pathname#each_line iterates over lines of the file. It’s yields a String object for each line.

This method is exist since 1.8.1.

[Source]

# File pathname.rb, line 337
  def each_line(*args, &block) IO.foreach(@path, *args, &block) end

Pathname#foreachline is obsoleted at 1.8.1.

[Source]

# File pathname.rb, line 341
  def foreachline(*args, &block) # compatibility to 1.8.0.  obsoleted.

    warn "Pathname#foreachline is obsoleted.  Use Pathname#each_line."
    each_line(*args, &block)
  end

[Source]

# File pathname.rb, line 346
  def read(*args) IO.read(@path, *args) end

[Source]

# File pathname.rb, line 347
  def readlines(*args) IO.readlines(@path, *args) end

[Source]

# File pathname.rb, line 348
  def sysopen(*args) IO.sysopen(@path, *args) end

[Source]

# File pathname.rb, line 353
  def atime() File.atime(@path) end

[Source]

# File pathname.rb, line 354
  def ctime() File.ctime(@path) end

[Source]

# File pathname.rb, line 355
  def mtime() File.mtime(@path) end

[Source]

# File pathname.rb, line 356
  def chmod(mode) File.chmod(mode, @path) end

[Source]

# File pathname.rb, line 357
  def lchmod(mode) File.chmod(mode, @path) end

[Source]

# File pathname.rb, line 358
  def chown(owner, group) File.chown(owner, group, @path) end

[Source]

# File pathname.rb, line 359
  def lchown(owner, group) File.lchown(owner, group, @path) end

[Source]

# File pathname.rb, line 360
  def fnmatch(pattern, *args) File.fnmatch(pattern, @path, *args) end

[Source]

# File pathname.rb, line 361
  def fnmatch?(pattern, *args) File.fnmatch?(pattern, @path, *args) end

[Source]

# File pathname.rb, line 362
  def ftype() File.ftype(@path) end

[Source]

# File pathname.rb, line 363
  def make_link(old) File.link(old, @path) end

[Source]

# File pathname.rb, line 364
  def open(*args, &block) File.open(@path, *args, &block) end

[Source]

# File pathname.rb, line 365
  def readlink() Pathname.new(File.readlink(@path)) end

[Source]

# File pathname.rb, line 366
  def rename(to) File.rename(@path, to) end

[Source]

# File pathname.rb, line 367
  def stat() File.stat(@path) end

[Source]

# File pathname.rb, line 368
  def lstat() File.lstat(@path) end

[Source]

# File pathname.rb, line 369
  def make_symlink(old) File.symlink(old, @path) end

[Source]

# File pathname.rb, line 370
  def truncate(length) File.truncate(@path, length) end

[Source]

# File pathname.rb, line 371
  def utime(atime, mtime) File.utime(atime, mtime, @path) end

[Source]

# File pathname.rb, line 372
  def basename(*args) Pathname.new(File.basename(@path, *args)) end

[Source]

# File pathname.rb, line 373
  def dirname() Pathname.new(File.dirname(@path)) end

[Source]

# File pathname.rb, line 374
  def extname() File.extname(@path) end

[Source]

# File pathname.rb, line 375
  def expand_path(*args) Pathname.new(File.expand_path(@path, *args)) end

[Source]

# File pathname.rb, line 376
  def split() File.split(@path).map {|f| Pathname.new(f) } end

Pathname#link is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.

[Source]

# File pathname.rb, line 380
  def link(old)
    warn 'Pathname#link is obsoleted.  Use Pathname#make_link.'
    File.link(old, @path)
  end

Pathname#symlink is confusing and obsoleted because the receiver/argument order is inverted to corresponding system call.

[Source]

# File pathname.rb, line 387
  def symlink(old)
    warn 'Pathname#symlink is obsoleted.  Use Pathname#make_symlink.'
    File.symlink(old, @path)
  end

[Source]

# File pathname.rb, line 395
  def blockdev?() FileTest.blockdev?(@path) end

[Source]

# File pathname.rb, line 396
  def chardev?() FileTest.chardev?(@path) end

[Source]

# File pathname.rb, line 397
  def executable?() FileTest.executable?(@path) end

[Source]

# File pathname.rb, line 398
  def executable_real?() FileTest.executable_real?(@path) end

[Source]

# File pathname.rb, line 399
  def exist?() FileTest.exist?(@path) end

[Source]

# File pathname.rb, line 400
  def grpowned?() FileTest.grpowned?(@path) end

[Source]

# File pathname.rb, line 401
  def directory?() FileTest.directory?(@path) end

[Source]

# File pathname.rb, line 402
  def file?() FileTest.file?(@path) end

[Source]

# File pathname.rb, line 403
  def pipe?() FileTest.pipe?(@path) end

[Source]

# File pathname.rb, line 404
  def socket?() FileTest.socket?(@path) end

[Source]

# File pathname.rb, line 405
  def owned?() FileTest.owned?(@path) end

[Source]

# File pathname.rb, line 406
  def readable?() FileTest.readable?(@path) end

[Source]

# File pathname.rb, line 407
  def readable_real?() FileTest.readable_real?(@path) end

[Source]

# File pathname.rb, line 408
  def setuid?() FileTest.setuid?(@path) end

[Source]

# File pathname.rb, line 409
  def setgid?() FileTest.setgid?(@path) end

[Source]

# File pathname.rb, line 410
  def size() FileTest.size(@path) end

[Source]

# File pathname.rb, line 411
  def size?() FileTest.size?(@path) end

[Source]

# File pathname.rb, line 412
  def sticky?() FileTest.sticky?(@path) end

[Source]

# File pathname.rb, line 413
  def symlink?() FileTest.symlink?(@path) end

[Source]

# File pathname.rb, line 414
  def writable?() FileTest.writable?(@path) end

[Source]

# File pathname.rb, line 415
  def writable_real?() FileTest.writable_real?(@path) end

[Source]

# File pathname.rb, line 416
  def zero?() FileTest.zero?(@path) end

Pathname#chdir is obsoleted at 1.8.1.

[Source]

# File pathname.rb, line 434
  def chdir(&block) # compatibility to 1.8.0.

    warn "Pathname#chdir is obsoleted.  Use Dir.chdir."
    Dir.chdir(@path, &block)
  end

Pathname#chroot is obsoleted at 1.8.1.

[Source]

# File pathname.rb, line 441
  def chroot # compatibility to 1.8.0.

    warn "Pathname#chroot is obsoleted.  Use Dir.chroot."
    Dir.chroot(@path)
  end

[Source]

# File pathname.rb, line 446
  def rmdir() Dir.rmdir(@path) end

[Source]

# File pathname.rb, line 447
  def entries() Dir.entries(@path).map {|f| Pathname.new(f) } end

Pathname#each_entry iterates over entries of the directory. It’s yields Pathname objects for each entry.

This method is exist since 1.8.1.

[Source]

# File pathname.rb, line 453
  def each_entry(&block) Dir.foreach(@path) {|f| yield Pathname.new(f) } end

  # Pathname#dir_foreach is obsoleted at 1.8.1.

  #

  def dir_foreach(*args, &block) # compatibility to 1.8.0.  obsoleted.

    warn "Pathname#dir_foreach is obsoleted.  Use Pathname#each_entry."
    each_entry(*args, &block)
  end

  def mkdir(*args) Dir.mkdir(@path, *args) end
  def opendir(&block) Dir.open(@path, &block) end
end

Pathname#dir_foreach is obsoleted at 1.8.1.

[Source]

# File pathname.rb, line 457
  def dir_foreach(*args, &block) # compatibility to 1.8.0.  obsoleted.

    warn "Pathname#dir_foreach is obsoleted.  Use Pathname#each_entry."
    each_entry(*args, &block)
  end

[Source]

# File pathname.rb, line 462
  def mkdir(*args) Dir.mkdir(@path, *args) end

[Source]

# File pathname.rb, line 463
  def opendir(&block) Dir.open(@path, &block) end

[Validate]