Class: Pathname
Relationships & Source Files | |
Inherits: | Object |
Defined in: | pathname_builtin.rb, pathname.c, pathname_builtin.rb, pathname_builtin.rb, pathname_builtin.rb, pathname_builtin.rb, pathname_builtin.rb |
Overview
Pathname
represents the name of a file or directory on the filesystem, but not the file itself.
The pathname depends on the Operating System: Unix, Windows, etc. This library works with pathnames of local OS, however non-Unix pathnames are supported experimentally.
A Pathname can be relative or absolute. It’s not until you try to reference the file that it even matters whether the file exists or not.
Pathname
is immutable. It has no method for destructive update.
The goal of this class is to manipulate file path information in a neater way than standard ::Ruby
provides. The examples below demonstrate the difference.
All functionality from ::File
, ::FileTest
, and some from ::Dir
and FileUtils is included, in an unsurprising way. It is essentially a facade for all of these, and more.
Examples
Example 1: Using Pathname
require 'pathname'
pn = Pathname.new("/usr/bin/ruby")
size = pn.size # 27662
isdir = pn.directory? # false
dir = pn.dirname # Pathname:/usr/bin
base = pn.basename # Pathname:ruby
dir, base = pn.split # [Pathname:/usr/bin, Pathname:ruby]
data = pn.read
pn.open { |f| _ }
pn.each_line { |line| _ }
Example 2: Using standard Ruby
pn = "/usr/bin/ruby"
size = File.size(pn) # 27662
isdir = File.directory?(pn) # false
dir = File.dirname(pn) # "/usr/bin"
base = File.basename(pn) # "ruby"
dir, base = File.split(pn) # ["/usr/bin", "ruby"]
data = File.read(pn)
File.open(pn) { |f| _ }
File.foreach(pn) { |line| _ }
Example 3: Special features
p1 = Pathname.new("/usr/lib") # Pathname:/usr/lib
p2 = p1 + "ruby/1.8" # Pathname:/usr/lib/ruby/1.8
p3 = p1.parent # Pathname:/usr
p4 = p2.relative_path_from(p3) # Pathname:lib/ruby/1.8
pwd = Pathname.pwd # Pathname:/home/gavin
pwd.absolute? # true
p5 = Pathname.new "." # Pathname:.
p5 = p5 + "music/../articles" # Pathname:music/../articles
p5.cleanpath # Pathname:articles
p5.realpath # Pathname:/home/gavin/articles
p5.children # [Pathname:/home/gavin/articles/linux, ...]
Breakdown of functionality
Core methods
These methods are effectively manipulating a ::String
, because that’s all a path is. None of these access the file system except for #mountpoint?, #children, #each_child, #realdirpath and #realpath.
-
+
File status predicate methods
These methods are a facade for ::FileTest
:
File property and manipulation methods
These methods are a facade for ::File
:
-
#each_line(*args, &block)
-
#read(*args)
-
#binread(*args)
-
#readlines(*args)
-
#sysopen(*args)
-
#write(*args)
-
#binwrite(*args)
-
#chmod(mode)
-
#lchmod(mode)
-
#chown(owner, group)
-
#lchown(owner, group)
-
#fnmatch(pattern, *args)
-
#fnmatch?(pattern, *args)
-
#make_link(old)
-
#open(*args, &block)
-
#rename(to)
-
#make_symlink(old)
-
#truncate(length)
-
#utime(atime, mtime)
-
#lutime(atime, mtime)
-
#basename(*args)
-
#expand_path(*args)
Directory methods
These methods are a facade for ::Dir
:
Utilities
These methods are a mixture of Find, FileUtils, and others:
Method documentation
As the above section shows, most of the methods in Pathname
are facades. The documentation for these methods generally just says, for instance, “See FileTest.writable?”
, as you should be familiar with the original method anyway, and its documentation (e.g. through ri
) will contain more information. In some cases, a brief description will follow.
Constant Summary
-
ABSOLUTE_PATH =
private
::Regexp
that matches an absoltute path./\A#{SEPARATOR_PAT}/
-
SAME_PATHS =
Internal use only
# File 'pathname_builtin.rb', line 201if File::FNM_SYSCASE.nonzero? # Avoid #zero? here because #casecmp can return nil. proc {|a, b| a.casecmp(b) == 0} else proc {|a, b| a == b} end
-
SEPARATOR_LIST =
Separator list string.
"#{Regexp.quote File::SEPARATOR}"
-
SEPARATOR_PAT =
::Regexp
that matches a separator./#{Regexp.quote File::SEPARATOR}/
-
TO_PATH =
Internal use only
to_path is implemented so
Pathname
objects are usable with File.open, etc.:to_path
-
VERSION =
The version string.
"0.4.0"
Class Method Summary
-
.getwd
(also: .pwd)
See Dir.getwd.
-
.glob(*args, **kwargs)
See Dir.glob.
-
.new(path) ⇒ Pathname
constructor
Create a
Pathname
object from the given::String
(or String-like object). -
.pwd
Alias for .getwd.
Instance Attribute Summary
-
#absolute? ⇒ Boolean
readonly
Predicate method for testing whether a path is absolute.
-
#empty? ⇒ Boolean
readonly
Tests the file is empty.
-
#mountpoint? ⇒ Boolean
readonly
Returns
true
ifself
points to a mountpoint. -
#relative? ⇒ Boolean
readonly
The opposite of #absolute?
-
#root? ⇒ Boolean
readonly
Predicate method for root directories.
- #path readonly protected Internal use only
Instance Method Summary
-
#+(other)
(also: #/)
Appends a pathname fragment to
self
to produce a newPathname
object. -
#/(other)
Alias for #+.
-
#<=>(other)
Provides a case-sensitive comparison operator for pathnames.
-
#==(other)
(also: #===, #eql?)
Compare this pathname with
other
. -
#===(other)
Alias for #==.
-
#ascend {|_self| ... }
Iterates over and yields a new
Pathname
object for each element in the given path in ascending order. -
#atime
See File.atime.
-
#basename
See File.basename.
-
#binread
See
File.binread
. -
#binwrite
Writes
contents
to the file, opening it in binary mode. -
#birthtime
Returns the birth time for the file.
-
#blockdev? ⇒ Boolean
See FileTest#blockdev?.
-
#chardev? ⇒ Boolean
See FileTest#chardev?.
-
#children(with_directory = true)
Returns the children of the directory (files and subdirectories, not recursive) as an array of
Pathname
objects. -
#chmod(mode)
See File.chmod.
-
#chown(owner, group)
See File.chown.
-
#cleanpath(consider_symlink = false)
Returns clean pathname of
self
with consecutive slashes and useless dots removed. -
#ctime
See File.ctime.
-
#delete
Alias for #unlink.
-
#descend
Iterates over and yields a new
Pathname
object for each element in the given path in descending order. -
#directory? ⇒ Boolean
See FileTest#directory?.
-
#dirname
See File.dirname.
-
#each_child(with_directory = true, &b)
Iterates over the children of the directory (files and subdirectories, not recursive).
-
#each_entry(&block)
Iterates over the entries (files and subdirectories) in the directory.
-
#each_filename
Iterates over each component of the path.
-
#each_line
#each_line iterates over the line in the file.
-
#entries
Return the entries (files and subdirectories) in the directory, each as a
Pathname
object. -
#eql?(other)
Alias for #==.
-
#executable? ⇒ Boolean
See FileTest#executable?.
- #executable_real? ⇒ Boolean
-
#exist? ⇒ Boolean
See FileTest#exist?.
-
#expand_path
See File.expand_path.
-
#extname
See File.extname.
-
#file? ⇒ Boolean
See FileTest#file?.
-
#fnmatch(pattern)
See File.fnmatch.
-
#fnmatch?(pattern) ⇒ Boolean
See File.fnmatch? (same as #fnmatch).
- #freeze
-
#ftype
See File.ftype.
-
#glob(*args, **kwargs)
Returns or yields
Pathname
objects. -
#grpowned? ⇒ Boolean
See FileTest#grpowned?.
-
#join(*args)
Joins the given pathnames onto
self
to create a newPathname
object. -
#lchmod(mode)
See File.lchmod.
-
#lchown(owner, group)
See File.lchown.
-
#lstat
See File.lstat.
-
#lutime(atime, mtime)
Update the access and modification times of the file.
-
#make_link(old)
See File.link.
-
#make_symlink(old)
See File.symlink.
-
#mkdir
See Dir.mkdir.
-
#mkpath(mode: nil)
Creates a full path, including any intermediate directories that don’t yet exist.
-
#mtime
See File.mtime.
-
#open
See File.open.
-
#opendir(&block)
See Dir.open.
-
#owned? ⇒ Boolean
See FileTest#owned?.
-
#parent
Returns the parent directory.
-
#pipe? ⇒ Boolean
See FileTest#pipe?.
-
#read
See
File.read
. -
#readable? ⇒ Boolean
See FileTest#readable?.
- #readable_real? ⇒ Boolean
-
#readlines
See
File.readlines
. -
#readlink
See File.readlink.
-
#realdirpath
Returns the real (absolute) pathname of
self
in the actual filesystem. -
#realpath
Returns the real (absolute) pathname for
self
in the actual filesystem. -
#relative_path_from(base_directory)
Returns a relative path from the given
base_directory
to the receiver. -
#rename(to)
See File.rename.
-
#rmdir
See Dir.rmdir.
-
#setgid? ⇒ Boolean
See FileTest#setgid?.
-
#setuid? ⇒ Boolean
See FileTest#setuid?.
-
#size
See FileTest#size.
-
#size? ⇒ Boolean
See FileTest#size?.
-
#socket? ⇒ Boolean
See FileTest#socket?.
-
#split
See File.split.
-
#stat
See File.stat.
-
#sticky? ⇒ Boolean
See FileTest#sticky?.
-
#sub(pattern, *args, **kwargs, &block)
Return a pathname which is substituted by String#sub.
-
#sub_ext(repl)
Return a pathname with
repl
added as a suffix to the basename. -
#symlink? ⇒ Boolean
See FileTest#symlink?.
-
#sysopen
See
File.sysopen
. -
#to_s
Return the path as a
::String
. -
#truncate(length)
See File.truncate.
-
#unlink
(also: #delete)
Removes a file or directory, using File.unlink or Dir.unlink as necessary.
-
#utime(atime, mtime)
See File.utime.
- #world_readable? ⇒ Boolean
- #world_writable? ⇒ Boolean
-
#writable? ⇒ Boolean
See FileTest#writable?.
- #writable_real? ⇒ Boolean
-
#write
Writes
contents
to the file. -
#zero? ⇒ Boolean
See FileTest#zero?.
- #hash Internal use only
- #inspect Internal use only
-
#add_trailing_separator(path)
private
Internal use only
add_trailing_separator(path) -> path.
-
#chop_basename(path)
private
Internal use only
chop_basename(path) -> [pre-basename, basename] or nil.
-
#cleanpath_aggressive
private
Internal use only
Clean the path simply by resolving and removing excess
.
and..
entries. - #cleanpath_conservative private Internal use only
- #del_trailing_separator(path) private Internal use only
-
#has_trailing_separator?(path) ⇒ Boolean
private
Internal use only
has_trailing_separator?(path) -> bool.
-
#plus(path1, path2)
private
Internal use only
-> path # :nodoc:
- #prepend_prefix(prefix, relpath) private Internal use only
-
#split_names(path)
private
Internal use only
split_names(path) -> prefix, [name, …].
Constructor Details
.new(path) ⇒ Pathname
Create a Pathname
object from the given ::String
(or String-like object). If #path contains a NUL character (\0
), an ::ArgumentError
is raised.
Class Method Details
.getwd Also known as: .pwd
See Dir.getwd. Returns the current working directory as a Pathname
.
.glob(*args, **kwargs)
See Dir.glob. Returns or yields Pathname
objects.
.pwd
Alias for .getwd.
# File 'pathname_builtin.rb', line 1125
alias pwd getwd
Instance Attribute Details
#absolute? ⇒ Boolean
(readonly)
# File 'pathname_builtin.rb', line 545
def absolute? ABSOLUTE_PATH.match? @path end
#empty? ⇒ Boolean
(readonly)
Tests the file is empty.
See Dir#empty?
and FileTest#empty?.
#mountpoint? ⇒ Boolean
(readonly)
Returns true
if self
points to a mountpoint.
#path (readonly, protected)
# File 'pathname_builtin.rb', line 208
attr_reader :path
#relative? ⇒ Boolean
(readonly)
The opposite of #absolute?
It returns false
if the pathname begins with a slash.
p = Pathname.new('/im/sure')
p.relative?
#=> false
p = Pathname.new('not/so/sure')
p.relative?
#=> true
# File 'pathname_builtin.rb', line 560
def relative? !absolute? end
#root? ⇒ Boolean
(readonly)
Predicate method for root directories. Returns true
if the pathname consists of consecutive slashes.
It doesn’t access the filesystem. So it may return false
for some pathnames which points to roots such as /usr/..
.
# File 'pathname_builtin.rb', line 530
def root? chop_basename(@path) == nil && /#{SEPARATOR_PAT}/o.match?(@path) end
Instance Method Details
#+(other) Also known as: #/
Appends a pathname fragment to self
to produce a new Pathname
object. Since other
is considered as a path relative to self
, if other
is an absolute path, the new Pathname
object is created from just other
.
p1 = Pathname.new("/usr") # Pathname:/usr
p2 = p1 + "bin/ruby" # Pathname:/usr/bin/ruby
p3 = p1 + "/etc/passwd" # Pathname:/etc/passwd
# / is aliased to +.
p4 = p1 / "bin/ruby" # Pathname:/usr/bin/ruby
p5 = p1 / "/etc/passwd" # Pathname:/etc/passwd
This method doesn’t access the file system; it is pure string manipulation.
#/(other)
Alias for #+.
# File 'pathname_builtin.rb', line 672
alias / +
#<=>(other)
Provides a case-sensitive comparison operator for pathnames.
Pathname.new('/usr') <=> Pathname.new('/usr/bin')
#=> -1
Pathname.new('/usr/bin') <=> Pathname.new('/usr/bin')
#=> 0
Pathname.new('/usr/bin') <=> Pathname.new('/USR/BIN')
#=> 1
It will return -1
, 0
or 1
depending on the value of the left argument relative to the right argument. Or it will return nil
if the arguments are not comparable.
# File 'pathname.c', line 31
static VALUE path_cmp(VALUE self, VALUE other) { VALUE s1, s2; char *p1, *p2; char *e1, *e2; if (!rb_obj_is_kind_of(other, rb_cPathname)) return Qnil; s1 = get_strpath(self); s2 = get_strpath(other); p1 = RSTRING_PTR(s1); p2 = RSTRING_PTR(s2); e1 = p1 + RSTRING_LEN(s1); e2 = p2 + RSTRING_LEN(s2); while (p1 < e1 && p2 < e2) { int c1, c2; c1 = (unsigned char)*p1++; c2 = (unsigned char)*p2++; if (c1 == '/') c1 = '\0'; if (c2 == '/') c2 = '\0'; if (c1 != c2) { if (c1 < c2) return INT2FIX(-1); else return INT2FIX(1); } } if (p1 < e1) return INT2FIX(1); if (p2 < e2) return INT2FIX(-1); return INT2FIX(0); }
#==(other) Also known as: #===, #eql?
Compare this pathname with other
. The comparison is string-based. Be aware that two different paths (foo.txt
and ./foo.txt
) can refer to the same file.
# File 'pathname_builtin.rb', line 241
def ==(other) return false unless Pathname === other other.path == @path end
#===(other)
Alias for #==.
# File 'pathname_builtin.rb', line 245
alias === ==
#add_trailing_separator(path) (private)
add_trailing_separator(path) -> path
#ascend {|_self| ... }
Iterates over and yields a new Pathname
object for each element in the given path in ascending order.
Pathname.new('/path/to/some/file.rb').ascend {|v| p v}
#<Pathname:/path/to/some/file.rb>
#<Pathname:/path/to/some>
#<Pathname:/path/to>
#<Pathname:/path>
#<Pathname:/>
Pathname.new('path/to/some/file.rb').ascend {|v| p v}
#<Pathname:path/to/some/file.rb>
#<Pathname:path/to/some>
#<Pathname:path/to>
#<Pathname:path>
Returns an ::Enumerator
if no block was given.
enum = Pathname.new("/usr/bin/ruby").ascend
# ... do stuff ...
enum.each { |e| ... }
# yields Pathnames /usr/bin/ruby, /usr/bin, /usr, and /.
It doesn’t access the filesystem.
# File 'pathname_builtin.rb', line 642
def ascend return to_enum(__method__) unless block_given? path = @path yield self while r = chop_basename(path) path, = r break if path.empty? yield self.class.new(del_trailing_separator(path)) end end
#atime
See File.atime. Returns last access time.
#basename
See File.basename. Returns the last component of the path.
#binread
See File.binread
. Returns all the bytes from the file, or the first N
if specified.
#binwrite
Writes contents
to the file, opening it in binary mode.
See File.binwrite
.
#birthtime
Returns the birth time for the file. If the platform doesn’t have birthtime, raises ::NotImplementedError
.
See File.birthtime.
#blockdev? ⇒ Boolean
See FileTest#blockdev?.
#chardev? ⇒ Boolean
See FileTest#chardev?.
#children(with_directory = true)
Returns the children of the directory (files and subdirectories, not recursive) as an array of Pathname
objects.
By default, the returned pathnames will have enough information to access the files. If you set with_directory
to false
, then the returned pathnames will contain the filename only.
For example:
pn = Pathname("/usr/lib/ruby/1.8")
pn.children
# -> [ Pathname:/usr/lib/ruby/1.8/English.rb,
Pathname:/usr/lib/ruby/1.8/Env.rb,
Pathname:/usr/lib/ruby/1.8/abbrev.rb, ... ]
pn.children(false)
# -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ]
Note that the results never contain the entries .
and ..
in the directory because they are not children.
#chmod(mode)
See File.chmod. Changes permissions.
#chop_basename(path) (private)
chop_basename(path) -> [pre-basename, basename] or nil
#chown(owner, group)
See File.chown. Change owner and group of file.
#cleanpath(consider_symlink = false)
Returns clean pathname of self
with consecutive slashes and useless dots removed. The filesystem is not accessed.
If consider_symlink
is true
, then a more conservative algorithm is used to avoid breaking symbolic linkages. This may retain more ..
entries than absolutely necessary, but without accessing the filesystem, this can’t be avoided.
See #realpath.
# File 'pathname_builtin.rb', line 406
def cleanpath(consider_symlink=false) if consider_symlink cleanpath_conservative else cleanpath_aggressive end end
#cleanpath_aggressive (private)
Clean the path simply by resolving and removing excess .
and ..
entries. Nothing more, nothing less.
# File 'pathname_builtin.rb', line 418
def cleanpath_aggressive # :nodoc: path = @path names = [] pre = path while r = chop_basename(pre) pre, base = r case base when '.' when '..' names.unshift base else if names[0] == '..' names.shift else names.unshift base end end end pre.tr!(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR if /#{SEPARATOR_PAT}/o.match?(File.basename(pre)) names.shift while names[0] == '..' end self.class.new(prepend_prefix(pre, File.join(*names))) end
#cleanpath_conservative (private)
# File 'pathname_builtin.rb', line 477
def cleanpath_conservative # :nodoc: path = @path names = [] pre = path while r = chop_basename(pre) pre, base = r names.unshift base if base != '.' end pre.tr!(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR if /#{SEPARATOR_PAT}/o.match?(File.basename(pre)) names.shift while names[0] == '..' end if names.empty? self.class.new(File.dirname(pre)) else if names.last != '..' && File.basename(path) == '.' names << '.' end result = prepend_prefix(pre, File.join(*names)) if /\A(?:\.|\.\.)\z/ !~ names.last && has_trailing_separator?(path) self.class.new(add_trailing_separator(result)) else self.class.new(result) end end end
#ctime
See File.ctime. Returns last (directory entry, not file) change time.
#del_trailing_separator(path) (private)
# File 'pathname_builtin.rb', line 465
def del_trailing_separator(path) # :nodoc: if r = chop_basename(path) pre, basename = r pre + basename elsif /#{SEPARATOR_PAT}+\z/o =~ path $` + File.dirname(path)[/#{SEPARATOR_PAT}*\z/o] else path end end
#delete
Alias for #unlink.
# File 'pathname_builtin.rb', line 1161
alias delete unlink
#descend
Iterates over and yields a new Pathname
object for each element in the given path in descending order.
Pathname.new('/path/to/some/file.rb').descend {|v| p v}
#<Pathname:/>
#<Pathname:/path>
#<Pathname:/path/to>
#<Pathname:/path/to/some>
#<Pathname:/path/to/some/file.rb>
Pathname.new('path/to/some/file.rb').descend {|v| p v}
#<Pathname:path>
#<Pathname:path/to>
#<Pathname:path/to/some>
#<Pathname:path/to/some/file.rb>
Returns an ::Enumerator
if no block was given.
enum = Pathname.new("/usr/bin/ruby").descend
# ... do stuff ...
enum.each { |e| ... }
# yields Pathnames /, /usr, /usr/bin, and /usr/bin/ruby.
It doesn’t access the filesystem.
# File 'pathname_builtin.rb', line 609
def descend return to_enum(__method__) unless block_given? vs = [] ascend {|v| vs << v } vs.reverse_each {|v| yield v } nil end
#directory? ⇒ Boolean
See FileTest#directory?.
# File 'pathname_builtin.rb', line 1042
def directory?() FileTest.directory?(@path) end
#dirname
See File.dirname. Returns all but the last component of the path.
#each_child(with_directory = true, &b)
Iterates over the children of the directory (files and subdirectories, not recursive).
It yields Pathname
object for each child.
By default, the yielded pathnames will have enough information to access the files.
If you set with_directory
to false
, then the returned pathnames will contain the filename only.
Pathname("/usr/local").each_child {|f| p f }
#=> #<Pathname:/usr/local/share>
# #<Pathname:/usr/local/bin>
# #<Pathname:/usr/local/games>
# #<Pathname:/usr/local/lib>
# #<Pathname:/usr/local/include>
# #<Pathname:/usr/local/sbin>
# #<Pathname:/usr/local/src>
# #<Pathname:/usr/local/man>
Pathname("/usr/local").each_child(false) {|f| p f }
#=> #<Pathname:share>
# #<Pathname:bin>
# #<Pathname:games>
# #<Pathname:lib>
# #<Pathname:include>
# #<Pathname:sbin>
# #<Pathname:src>
# #<Pathname:man>
Note that the results never contain the entries .
and ..
in the directory because they are not children.
See #children
# File 'pathname_builtin.rb', line 811
def each_child(with_directory=true, &b) children(with_directory).each(&b) end
#each_entry(&block)
Iterates over the entries (files and subdirectories) in the directory. It yields a Pathname
object for each entry.
This method has existed since 1.8.1.
#each_filename
Iterates over each component of the path.
Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
# yields "usr", "bin", and "ruby".
Returns an ::Enumerator
if no block was given.
enum = Pathname.new("/usr/bin/ruby").each_filename
# ... do stuff ...
enum.each { |e| ... }
# yields "usr", "bin", and "ruby".
# File 'pathname_builtin.rb', line 577
def each_filename # :yield: filename return to_enum(__method__) unless block_given? _, names = split_names(@path) names.each {|filename| yield filename } nil end
#each_line
#each_line
iterates over the line in the file. It yields a ::String
object for each line.
This method has existed since 1.8.1.
#entries
Return the entries (files and subdirectories) in the directory, each as a Pathname
object.
#eql?(other)
Alias for #==.
# File 'pathname_builtin.rb', line 246
alias eql? ==
#executable? ⇒ Boolean
See FileTest#executable?.
# File 'pathname_builtin.rb', line 1030
def executable?() FileTest.executable?(@path) end
#executable_real? ⇒ Boolean
[ GitHub ]
# File 'pathname_builtin.rb', line 1033
def executable_real?() FileTest.executable_real?(@path) end
#exist? ⇒ Boolean
See FileTest#exist?.
#expand_path
See File.expand_path.
#extname
See File.extname. Returns the file’s extension.
#file? ⇒ Boolean
See FileTest#file?.
#fnmatch(pattern)
See File.fnmatch. Return true
if the receiver matches the given pattern.
#fnmatch?(pattern) ⇒ Boolean
See File.fnmatch? (same as #fnmatch).
# File 'pathname_builtin.rb', line 932
def fnmatch?(pattern, ...) File.fnmatch?(pattern, @path, ...) end
#freeze
[ GitHub ]# File 'pathname_builtin.rb', line 230
def freeze super @path.freeze self end
#ftype
See File.ftype. Returns “type” of file (“file”, “directory”, etc).
#glob(*args, **kwargs)
#grpowned? ⇒ Boolean
See FileTest#grpowned?.
#has_trailing_separator?(path) ⇒ Boolean
(private)
has_trailing_separator?(path) -> bool
#hash
# File 'pathname_builtin.rb', line 256
def hash # :nodoc: @path.hash end
#inspect
# File 'pathname_builtin.rb', line 268
def inspect # :nodoc: "#<#{self.class}:#{@path}>" end
#join(*args)
Joins the given pathnames onto self
to create a new Pathname
object. This is effectively the same as using #+ to append self
and all arguments sequentially.
path0 = Pathname.new("/usr") # Pathname:/usr
path0 = path0.join("bin/ruby") # Pathname:/usr/bin/ruby
# is the same as
path1 = Pathname.new("/usr") + "bin/ruby" # Pathname:/usr/bin/ruby
path0 == path1
#=> true
# File 'pathname_builtin.rb', line 728
def join(*args) return self if args.empty? result = args.pop result = Pathname.new(result) unless Pathname === result return result if result.absolute? args.reverse_each {|arg| arg = Pathname.new(arg) unless Pathname === arg result = arg + result return result if result.absolute? } self + result end
#lchmod(mode)
See File.lchmod.
#lchown(owner, group)
See File.lchown.
#lstat
See File.lstat.
#lutime(atime, mtime)
Update the access and modification times of the file.
Same as #utime, but does not follow symbolic links.
See File.lutime.
#make_link(old)
See File.link. Creates a hard link.
#make_symlink(old)
See File.symlink. Creates a symbolic link.
#mkdir
See Dir.mkdir. Create the referenced directory.
#mkpath(mode: nil)
Creates a full path, including any intermediate directories that don’t yet exist.
See FileUtils.mkpath
and FileUtils.mkdir_p
# File 'pathname_builtin.rb', line 337
def mkpath(mode: nil) path = @path == '/' ? @path : @path.chomp('/') stack = [] until File.directory?(path) || File.dirname(path) == path stack.push path path = File.dirname(path) end stack.reverse_each do |dir| dir = dir == '/' ? dir : dir.chomp('/') if mode Dir.mkdir dir, mode File.chmod mode, dir else Dir.mkdir dir end rescue SystemCallError raise unless File.directory?(dir) end self end
#mtime
See File.mtime. Returns last modification time.
#open
See File.open. Opens the file for reading or writing.
#opendir(&block)
See Dir.open.
#owned? ⇒ Boolean
See FileTest#owned?.
#parent
Returns the parent directory.
This is same as self + '..'
.
# File 'pathname_builtin.rb', line 508
def parent self + '..' end
#pipe? ⇒ Boolean
See FileTest#pipe?.
#plus(path1, path2) (private)
-> path # :nodoc:
# File 'pathname_builtin.rb', line 674
def plus(path1, path2) # -> path # :nodoc: prefix2 = path2 index_list2 = [] basename_list2 = [] while r2 = chop_basename(prefix2) prefix2, basename2 = r2 index_list2.unshift prefix2.length basename_list2.unshift basename2 end return path2 if prefix2 != '' prefix1 = path1 while true while !basename_list2.empty? && basename_list2.first == '.' index_list2.shift basename_list2.shift end break unless r1 = chop_basename(prefix1) prefix1, basename1 = r1 next if basename1 == '.' if basename1 == '..' || basename_list2.empty? || basename_list2.first != '..' prefix1 = prefix1 + basename1 break end index_list2.shift basename_list2.shift end r1 = chop_basename(prefix1) if !r1 && (r1 = /#{SEPARATOR_PAT}/o.match?(File.basename(prefix1))) while !basename_list2.empty? && basename_list2.first == '..' index_list2.shift basename_list2.shift end end if !basename_list2.empty? suffix2 = path2[index_list2.first..-1] r1 ? File.join(prefix1, suffix2) : prefix1 + suffix2 else r1 ? prefix1 : File.dirname(prefix1) end end
#prepend_prefix(prefix, relpath) (private)
# File 'pathname_builtin.rb', line 383
def prepend_prefix(prefix, relpath) # :nodoc: if relpath.empty? File.dirname(prefix) elsif /#{SEPARATOR_PAT}/o.match?(prefix) prefix = File.dirname(prefix) prefix = File.join(prefix, "") if File.basename(prefix + 'a') != 'a' prefix + relpath else prefix + relpath end end
#read
See File.read
. Returns all data from the file, or the first N
bytes if specified.
#readable? ⇒ Boolean
See FileTest#readable?.
#readable_real? ⇒ Boolean
[ GitHub ]
# File 'pathname_builtin.rb', line 1063
def readable_real?() FileTest.readable_real?(@path) end
#readlines
See File.readlines
. Returns all the lines from the file.
#readlink
See File.readlink. Read symbolic link.
#realdirpath
Returns the real (absolute) pathname of self
in the actual filesystem.
Does not contain symlinks or useless dots, ..
and .
.
The last component of the real pathname can be nonexistent.
# File 'pathname_builtin.rb', line 1006
def realdirpath(...) self.class.new(File.realdirpath(@path, ...)) end
#realpath
Returns the real (absolute) pathname for self
in the actual filesystem.
Does not contain symlinks or useless dots, ..
and .
.
All components of the pathname must exist when this method is called.
#relative_path_from(base_directory)
Returns a relative path from the given base_directory
to the receiver.
If self
is absolute, then base_directory
must be absolute too.
If self
is relative, then base_directory
must be relative too.
This method doesn’t access the filesystem. It assumes no symlinks.
::ArgumentError
is raised when it cannot find a relative path.
Note that this method does not handle situations where the case sensitivity of the filesystem in use differs from the operating system default.
# File 'pathname_builtin.rb', line 829
def relative_path_from(base_directory) base_directory = Pathname.new(base_directory) unless base_directory.is_a? Pathname dest_directory = self.cleanpath.path base_directory = base_directory.cleanpath.path dest_prefix = dest_directory dest_names = [] while r = chop_basename(dest_prefix) dest_prefix, basename = r dest_names.unshift basename if basename != '.' end base_prefix = base_directory base_names = [] while r = chop_basename(base_prefix) base_prefix, basename = r base_names.unshift basename if basename != '.' end unless SAME_PATHS[dest_prefix, base_prefix] raise ArgumentError, "different prefix: #{dest_prefix.inspect} and #{base_directory.inspect}" end while !dest_names.empty? && !base_names.empty? && SAME_PATHS[dest_names.first, base_names.first] dest_names.shift base_names.shift end if base_names.include? '..' raise ArgumentError, "base_directory has ..: #{base_directory.inspect}" end base_names.fill('..') relpath_names = base_names + dest_names if relpath_names.empty? Pathname.new('.') else Pathname.new(File.join(*relpath_names)) end end
#rename(to)
See File.rename. Rename the file.
#rmdir
See Dir.rmdir. Remove the referenced directory.
#setgid? ⇒ Boolean
See FileTest#setgid?.
#setuid? ⇒ Boolean
See FileTest#setuid?.
#size
See FileTest#size.
#size? ⇒ Boolean
See FileTest#size?.
#socket? ⇒ Boolean
See FileTest#socket?.
#split
See File.split. Returns the #dirname and the #basename in an ::Array
.
#split_names(path) (private)
split_names(path) -> prefix, [name, …]
#stat
See File.stat. Returns a ::File::Stat
object.
#sticky? ⇒ Boolean
See FileTest#sticky?.
#sub(pattern, *args, **kwargs, &block)
Return a pathname which is substituted by String#sub.
path1 = Pathname.new('/usr/bin/perl')
path1.sub('perl', 'ruby')
#=> #<Pathname:/usr/bin/ruby>
# File 'pathname.c', line 72
static VALUE path_sub(int argc, VALUE *argv, VALUE self) { VALUE str = get_strpath(self); if (rb_block_given_p()) { str = rb_block_call(str, id_sub, argc, argv, 0, 0); } else { str = rb_funcallv(str, id_sub, argc, argv); } return rb_class_new_instance(1, &str, rb_obj_class(self)); }
#sub_ext(repl)
Return a pathname with repl
added as a suffix to the basename.
If self has no extension part, repl
is appended.
Pathname.new('/usr/bin/shutdown').sub_ext('.rb')
#=> #<Pathname:/usr/bin/shutdown.rb>
# File 'pathname_builtin.rb', line 299
def sub_ext(repl) ext = File.extname(@path) # File.extname("foo.bar:stream") returns ".bar" on NTFS and not ".bar:stream" # (see ruby_enc_find_extname()). # The behavior of Pathname#sub_ext is to replace everything # from the start of the extname until the end of the path with repl. unless @path.end_with?(ext) ext = @path[@path.rindex(ext)..] end self.class.new(@path.chomp(ext) + repl) end
#symlink? ⇒ Boolean
See FileTest#symlink?.
#sysopen
See File.sysopen
.
#to_s
Return the path as a ::String
.
# File 'pathname_builtin.rb', line 261
def to_s @path.dup end
#truncate(length)
See File.truncate. Truncate the file to length
bytes.
#unlink Also known as: #delete
Removes a file or directory, using File.unlink or Dir.unlink as necessary.
#utime(atime, mtime)
See File.utime. Update the access and modification times.
#world_readable? ⇒ Boolean
[ GitHub ]
# File 'pathname_builtin.rb', line 1060
def world_readable?() File.world_readable?(@path) end
#world_writable? ⇒ Boolean
[ GitHub ]
# File 'pathname_builtin.rb', line 1087
def world_writable?() File.world_writable?(@path) end
#writable? ⇒ Boolean
See FileTest#writable?.
#writable_real? ⇒ Boolean
[ GitHub ]
# File 'pathname_builtin.rb', line 1090
def writable_real?() FileTest.writable_real?(@path) end
#write
Writes contents
to the file. See File.write
.
#zero? ⇒ Boolean
See FileTest#zero?.