# 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

new(path)

[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

glob(*args) {|Pathname.new(f) }| ...}

[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

getwd()

[Source]

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

pwd()

Alias for getwd

## Public Instance methods

==(other)

[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 #==

<=>(other)

[Source]

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

hash()

[Source]

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

to_s()

[Source]

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

to_str()

Alias for to_s

inspect()

[Source]

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

cleanpath(consider_symlink=false)

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(*args)

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()

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?()

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?()

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?()

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?()

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() {|$& }| ...}

each_filename iterates over self for each filename components.

[Source]

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

+(other)

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

join(*args)

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

children(with_directory=true)

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

relative_path_from(base_directory)

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

each_line(*args, &block)

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

foreachline(*args, &block)

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

read(*args)

[Source]

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

readlines(*args)

[Source]

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

sysopen(*args)

[Source]

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

atime()

[Source]

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

ctime()

[Source]

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

mtime()

[Source]

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

chmod(mode)

[Source]

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

lchmod(mode)

[Source]

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

chown(owner, group)

[Source]

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

lchown(owner, group)

[Source]

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

fnmatch(pattern, *args)

[Source]

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

fnmatch?(pattern, *args)

[Source]

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

ftype()

[Source]

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

make_link(old)

[Source]

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

open(*args, &block)

[Source]

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

readlink()

[Source]

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

rename(to)

[Source]

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

stat()

[Source]

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

lstat()

[Source]

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

make_symlink(old)

[Source]

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

truncate(length)

[Source]

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

utime(atime, mtime)

[Source]

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

basename(*args)

[Source]

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

dirname()

[Source]

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

extname()

[Source]

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

expand_path(*args)

[Source]

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

split()

[Source]

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

link(old)

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

symlink(old)

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

blockdev?()

[Source]

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

chardev?()

[Source]

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

executable?()

[Source]

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

executable_real?()

[Source]

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

exist?()

[Source]

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

grpowned?()

[Source]

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

directory?()

[Source]

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

file?()

[Source]

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

pipe?()

[Source]

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

socket?()

[Source]

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

owned?()

[Source]

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

readable?()

[Source]

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

readable_real?()

[Source]

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

setuid?()

[Source]

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

setgid?()

[Source]

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

size()

[Source]

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

size?()

[Source]

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

sticky?()

[Source]

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

symlink?()

[Source]

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

writable?()

[Source]

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

writable_real?()

[Source]

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

zero?()

[Source]

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

chdir(&block)

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

chroot()

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

rmdir()

[Source]

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

entries()

[Source]

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

each_entry(&block) {|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

dir_foreach(*args, &block)

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

mkdir(*args)

[Source]

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

opendir(&block)

[Source]

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

[Validate]