| blob | 7bee22b58fc4050fce90855f16812a134918cfac |
1 #
2 # = pathname.rb
3 #
4 # Object-Oriented Pathname Class
5 #
6 # Author:: Tanaka Akira <akr@m17n.org>
7 # Documentation:: Author and Gavin Sinclair
8 #
9 # For documentation, see class Pathname.
10 #
11 # <tt>pathname.rb</tt> is distributed with Ruby since 1.8.0.
12 #
14 #
15 # == Pathname
16 #
17 # Pathname represents a pathname which locates a file in a filesystem.
18 # The pathname depends on OS: Unix, Windows, etc.
19 # Pathname library works with pathnames of local OS.
20 # However non-Unix pathnames are supported experimentally.
21 #
22 # It does not represent the file itself.
23 # A Pathname can be relative or absolute. It's not until you try to
24 # reference the file that it even matters whether the file exists or not.
25 #
26 # Pathname is immutable. It has no method for destructive update.
27 #
28 # The value of this class is to manipulate file path information in a neater
29 # way than standard Ruby provides. The examples below demonstrate the
30 # difference. *All* functionality from File, FileTest, and some from Dir and
31 # FileUtils is included, in an unsurprising way. It is essentially a facade for
32 # all of these, and more.
33 #
34 # == Examples
35 #
36 # === Example 1: Using Pathname
37 #
38 # require 'pathname'
39 # p = Pathname.new("/usr/bin/ruby")
40 # size = p.size # 27662
41 # isdir = p.directory? # false
42 # dir = p.dirname # Pathname:/usr/bin
43 # base = p.basename # Pathname:ruby
44 # dir, base = p.split # [Pathname:/usr/bin, Pathname:ruby]
45 # data = p.read
46 # p.open { |f| _ }
47 # p.each_line { |line| _ }
48 #
49 # === Example 2: Using standard Ruby
50 #
51 # p = "/usr/bin/ruby"
52 # size = File.size(p) # 27662
53 # isdir = File.directory?(p) # false
54 # dir = File.dirname(p) # "/usr/bin"
55 # base = File.basename(p) # "ruby"
56 # dir, base = File.split(p) # ["/usr/bin", "ruby"]
57 # data = File.read(p)
58 # File.open(p) { |f| _ }
59 # File.foreach(p) { |line| _ }
60 #
61 # === Example 3: Special features
62 #
63 # p1 = Pathname.new("/usr/lib") # Pathname:/usr/lib
64 # p2 = p1 + "ruby/1.8" # Pathname:/usr/lib/ruby/1.8
65 # p3 = p1.parent # Pathname:/usr
66 # p4 = p2.relative_path_from(p3) # Pathname:lib/ruby/1.8
67 # pwd = Pathname.pwd # Pathname:/home/gavin
68 # pwd.absolute? # true
69 # p5 = Pathname.new "." # Pathname:.
70 # p5 = p5 + "music/../articles" # Pathname:music/../articles
71 # p5.cleanpath # Pathname:articles
72 # p5.realpath # Pathname:/home/gavin/articles
73 # p5.children # [Pathname:/home/gavin/articles/linux, ...]
74 #
75 # == Breakdown of functionality
76 #
77 # === Core methods
78 #
79 # These methods are effectively manipulating a String, because that's all a path
80 # is. Except for #mountpoint?, #children, and #realpath, they don't access the
81 # filesystem.
82 #
83 # - +
84 # - #join
85 # - #parent
86 # - #root?
87 # - #absolute?
88 # - #relative?
89 # - #relative_path_from
90 # - #each_filename
91 # - #cleanpath
92 # - #realpath
93 # - #children
94 # - #mountpoint?
95 #
96 # === File status predicate methods
97 #
98 # These methods are a facade for FileTest:
99 # - #blockdev?
100 # - #chardev?
101 # - #directory?
102 # - #executable?
103 # - #executable_real?
104 # - #exist?
105 # - #file?
106 # - #grpowned?
107 # - #owned?
108 # - #pipe?
109 # - #readable?
110 # - #world_readable?
111 # - #readable_real?
112 # - #setgid?
113 # - #setuid?
114 # - #size
115 # - #size?
116 # - #socket?
117 # - #sticky?
118 # - #symlink?
119 # - #writable?
120 # - #world_writable?
121 # - #writable_real?
122 # - #zero?
123 #
124 # === File property and manipulation methods
125 #
126 # These methods are a facade for File:
127 # - #atime
128 # - #ctime
129 # - #mtime
130 # - #chmod(mode)
131 # - #lchmod(mode)
132 # - #chown(owner, group)
133 # - #lchown(owner, group)
134 # - #fnmatch(pattern, *args)
135 # - #fnmatch?(pattern, *args)
136 # - #ftype
137 # - #make_link(old)
138 # - #open(*args, &block)
139 # - #readlink
140 # - #rename(to)
141 # - #stat
142 # - #lstat
143 # - #make_symlink(old)
144 # - #truncate(length)
145 # - #utime(atime, mtime)
146 # - #basename(*args)
147 # - #dirname
148 # - #extname
149 # - #expand_path(*args)
150 # - #split
151 #
152 # === Directory methods
153 #
154 # These methods are a facade for Dir:
155 # - Pathname.glob(*args)
156 # - Pathname.getwd / Pathname.pwd
157 # - #rmdir
158 # - #entries
159 # - #each_entry(&block)
160 # - #mkdir(*args)
161 # - #opendir(*args)
162 #
163 # === IO
164 #
165 # These methods are a facade for IO:
166 # - #each_line(*args, &block)
167 # - #read(*args)
168 # - #readlines(*args)
169 # - #sysopen(*args)
170 #
171 # === Utilities
172 #
173 # These methods are a mixture of Find, FileUtils, and others:
174 # - #find(&block)
175 # - #mkpath
176 # - #rmtree
177 # - #unlink / #delete
178 #
179 #
180 # == Method documentation
181 #
182 # As the above section shows, most of the methods in Pathname are facades. The
183 # documentation for these methods generally just says, for instance, "See
184 # FileTest.writable?", as you should be familiar with the original method
185 # anyway, and its documentation (e.g. through +ri+) will contain more
186 # information. In some cases, a brief description will follow.
187 #
188 class Pathname
190 # :stopdoc:
191 if RUBY_VERSION < "1.9"
192 TO_PATH = :to_str
193 else
194 # to_path is implemented so Pathname objects are usable with File.open, etc.
195 TO_PATH = :to_path
196 end
197 # :startdoc:
199 #
200 # Create a Pathname object from the given String (or String-like object).
201 # If +path+ contains a NUL character (<tt>\0</tt>), an ArgumentError is raised.
202 #
203 def initialize(path)
204 path = path.__send__(TO_PATH) if path.respond_to? TO_PATH
205 @path = path.dup
207 if /\0/ =~ @path
208 raise ArgumentError, "pathname contains \\0: #{@path.inspect}"
209 end
211 self.taint if @path.tainted?
212 end
214 def freeze() super; @path.freeze; self end
215 def taint() super; @path.taint; self end
216 def untaint() super; @path.untaint; self end
218 #
219 # Compare this pathname with +other+. The comparison is string-based.
220 # Be aware that two different paths (<tt>foo.txt</tt> and <tt>./foo.txt</tt>)
221 # can refer to the same file.
222 #
223 def ==(other)
224 return false unless Pathname === other
225 other.to_s == @path
226 end
227 alias === ==
228 alias eql? ==
230 # Provides for comparing pathnames, case-sensitively.
231 def <=>(other)
232 return nil unless Pathname === other
233 @path.tr('/', "\0") <=> other.to_s.tr('/', "\0")
234 end
236 def hash # :nodoc:
237 @path.hash
238 end
240 # Return the path as a String.
241 def to_s
242 @path.dup
243 end
245 # to_path is implemented so Pathname objects are usable with File.open, etc.
246 alias_method TO_PATH, :to_s
248 def inspect # :nodoc:
249 "#<#{self.class}:#{@path}>"
250 end
252 # Return a pathname which is substituted by String#sub.
253 def sub(pattern, *rest, &block)
254 self.class.new(@path.sub(pattern, *rest, &block))
255 end
257 if File::ALT_SEPARATOR
258 SEPARATOR_LIST = "#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}"
259 SEPARATOR_PAT = /[#{SEPARATOR_LIST}]/
260 else
261 SEPARATOR_LIST = "#{Regexp.quote File::SEPARATOR}"
262 SEPARATOR_PAT = /#{Regexp.quote File::SEPARATOR}/
263 end
265 # Return a pathname which the extension of the basename is substituted by
266 # <i>repl</i>.
267 #
268 # If self has no extension part, <i>repl</i> is appended.
269 def sub_ext(repl)
270 ext = File.extname(@path)
271 self.class.new(@path.chomp(ext) + repl)
272 end
274 # chop_basename(path) -> [pre-basename, basename] or nil
275 def chop_basename(path)
276 base = File.basename(path)
277 if /\A#{SEPARATOR_PAT}?\z/ =~ base
278 return nil
279 else
280 return path[0, path.rindex(base)], base
281 end
282 end
283 private :chop_basename
285 # split_names(path) -> prefix, [name, ...]
286 def split_names(path)
287 names = []
288 while r = chop_basename(path)
289 path, basename = r
290 names.unshift basename
291 end
292 return path, names
293 end
294 private :split_names
296 def prepend_prefix(prefix, relpath)
297 if relpath.empty?
298 File.dirname(prefix)
299 elsif /#{SEPARATOR_PAT}/ =~ prefix
300 prefix = File.dirname(prefix)
301 prefix = File.join(prefix, "") if File.basename(prefix + 'a') != 'a'
302 prefix + relpath
303 else
304 prefix + relpath
305 end
306 end
307 private :prepend_prefix
309 # Returns clean pathname of +self+ with consecutive slashes and useless dots
310 # removed. The filesystem is not accessed.
311 #
312 # If +consider_symlink+ is +true+, then a more conservative algorithm is used
313 # to avoid breaking symbolic linkages. This may retain more <tt>..</tt>
314 # entries than absolutely necessary, but without accessing the filesystem,
315 # this can't be avoided. See #realpath.
316 #
317 def cleanpath(consider_symlink=false)
318 if consider_symlink
319 cleanpath_conservative
320 else
321 cleanpath_aggressive
322 end
323 end
325 #
326 # Clean the path simply by resolving and removing excess "." and ".." entries.
327 # Nothing more, nothing less.
328 #
329 def cleanpath_aggressive
330 path = @path
331 names = []
332 pre = path
333 while r = chop_basename(pre)
334 pre, base = r
335 case base
336 when '.'
337 when '..'
338 names.unshift base
339 else
340 if names[0] == '..'
341 names.shift
342 else
343 names.unshift base
344 end
345 end
346 end
347 if /#{SEPARATOR_PAT}/o =~ File.basename(pre)
348 names.shift while names[0] == '..'
349 end
350 self.class.new(prepend_prefix(pre, File.join(*names)))
351 end
352 private :cleanpath_aggressive
354 # has_trailing_separator?(path) -> bool
355 def has_trailing_separator?(path)
356 if r = chop_basename(path)
357 pre, basename = r
358 pre.length + basename.length < path.length
359 else
360 false
361 end
362 end
363 private :has_trailing_separator?
365 # add_trailing_separator(path) -> path
366 def add_trailing_separator(path)
367 if File.basename(path + 'a') == 'a'
368 path
369 else
370 File.join(path, "") # xxx: Is File.join is appropriate to add separator?
371 end
372 end
373 private :add_trailing_separator
375 def del_trailing_separator(path)
376 if r = chop_basename(path)
377 pre, basename = r
378 pre + basename
379 elsif /#{SEPARATOR_PAT}+\z/o =~ path
380 $` + File.dirname(path)[/#{SEPARATOR_PAT}*\z/o]
381 else
382 path
383 end
384 end
385 private :del_trailing_separator
387 def cleanpath_conservative
388 path = @path
389 names = []
390 pre = path
391 while r = chop_basename(pre)
392 pre, base = r
393 names.unshift base if base != '.'
394 end
395 if /#{SEPARATOR_PAT}/o =~ File.basename(pre)
396 names.shift while names[0] == '..'
397 end
398 if names.empty?
399 self.class.new(File.dirname(pre))
400 else
401 if names.last != '..' && File.basename(path) == '.'
402 names << '.'
403 end
404 result = prepend_prefix(pre, File.join(*names))
405 if /\A(?:\.|\.\.)\z/ !~ names.last && has_trailing_separator?(path)
406 self.class.new(add_trailing_separator(result))
407 else
408 self.class.new(result)
409 end
410 end
411 end
412 private :cleanpath_conservative
414 def realpath_rec(prefix, unresolved, h)
415 resolved = []
416 until unresolved.empty?
417 n = unresolved.shift
418 if n == '.'
419 next
420 elsif n == '..'
421 resolved.pop
422 else
423 path = prepend_prefix(prefix, File.join(*(resolved + [n])))
424 if h.include? path
425 if h[path] == :resolving
426 raise Errno::ELOOP.new(path)
427 else
428 prefix, *resolved = h[path]
429 end
430 else
431 s = File.lstat(path)
432 if s.symlink?
433 h[path] = :resolving
434 link_prefix, link_names = split_names(File.readlink(path))
435 if link_prefix == ''
436 prefix, *resolved = h[path] = realpath_rec(prefix, resolved + link_names, h)
437 else
438 prefix, *resolved = h[path] = realpath_rec(link_prefix, link_names, h)
439 end
440 else
441 resolved << n
442 h[path] = [prefix, *resolved]
443 end
444 end
445 end
446 end
447 return prefix, *resolved
448 end
449 private :realpath_rec
451 #
452 # Returns a real (absolute) pathname of +self+ in the actual filesystem.
453 # The real pathname doesn't contain symlinks or useless dots.
454 #
455 # No arguments should be given; the old behaviour is *obsoleted*.
456 #
457 def realpath
458 path = @path
459 prefix, names = split_names(path)
460 if prefix == ''
461 prefix, names2 = split_names(Dir.pwd)
462 names = names2 + names
463 end
464 prefix, *names = realpath_rec(prefix, names, {})
465 self.class.new(prepend_prefix(prefix, File.join(*names)))
466 end
468 # #parent returns the parent directory.
469 #
470 # This is same as <tt>self + '..'</tt>.
471 def parent
472 self + '..'
473 end
475 # #mountpoint? returns +true+ if <tt>self</tt> points to a mountpoint.
476 def mountpoint?
477 begin
478 stat1 = self.lstat
479 stat2 = self.parent.lstat
480 stat1.dev == stat2.dev && stat1.ino == stat2.ino ||
481 stat1.dev != stat2.dev
482 rescue Errno::ENOENT
483 false
484 end
485 end
487 #
488 # #root? is a predicate for root directories. I.e. it returns +true+ if the
489 # pathname consists of consecutive slashes.
490 #
491 # It doesn't access actual filesystem. So it may return +false+ for some
492 # pathnames which points to roots such as <tt>/usr/..</tt>.
493 #
494 def root?
495 !!(chop_basename(@path) == nil && /#{SEPARATOR_PAT}/o =~ @path)
496 end
498 # Predicate method for testing whether a path is absolute.
499 # It returns +true+ if the pathname begins with a slash.
500 def absolute?
501 !relative?
502 end
504 # The opposite of #absolute?
505 def relative?
506 path = @path
507 while r = chop_basename(path)
508 path, basename = r
509 end
510 path == ''
511 end
513 #
514 # Iterates over each component of the path.
515 #
516 # Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
517 # # yields "usr", "bin", and "ruby".
518 #
519 def each_filename # :yield: filename
520 prefix, names = split_names(@path)
521 names.each {|filename| yield filename }
522 nil
523 end
525 # Iterates over and yields a new Pathname object
526 # for each element in the given path in descending order.
527 #
528 # Pathname.new('/path/to/some/file.rb').descend {|v| p v}
529 # #<Pathname:/>
530 # #<Pathname:/path>
531 # #<Pathname:/path/to>
532 # #<Pathname:/path/to/some>
533 # #<Pathname:/path/to/some/file.rb>
534 #
535 # Pathname.new('path/to/some/file.rb').descend {|v| p v}
536 # #<Pathname:path>
537 # #<Pathname:path/to>
538 # #<Pathname:path/to/some>
539 # #<Pathname:path/to/some/file.rb>
540 #
541 # It doesn't access actual filesystem.
542 #
543 # This method is available since 1.8.5.
544 #
545 def descend
546 vs = []
547 ascend {|v| vs << v }
548 vs.reverse_each {|v| yield v }
549 nil
550 end
552 # Iterates over and yields a new Pathname object
553 # for each element in the given path in ascending order.
554 #
555 # Pathname.new('/path/to/some/file.rb').ascend {|v| p v}
556 # #<Pathname:/path/to/some/file.rb>
557 # #<Pathname:/path/to/some>
558 # #<Pathname:/path/to>
559 # #<Pathname:/path>
560 # #<Pathname:/>
561 #
562 # Pathname.new('path/to/some/file.rb').ascend {|v| p v}
563 # #<Pathname:path/to/some/file.rb>
564 # #<Pathname:path/to/some>
565 # #<Pathname:path/to>
566 # #<Pathname:path>
567 #
568 # It doesn't access actual filesystem.
569 #
570 # This method is available since 1.8.5.
571 #
572 def ascend
573 path = @path
574 yield self
575 while r = chop_basename(path)
576 path, name = r
577 break if path.empty?
578 yield self.class.new(del_trailing_separator(path))
579 end
580 end
582 #
583 # Pathname#+ appends a pathname fragment to this one to produce a new Pathname
584 # object.
585 #
586 # p1 = Pathname.new("/usr") # Pathname:/usr
587 # p2 = p1 + "bin/ruby" # Pathname:/usr/bin/ruby
588 # p3 = p1 + "/etc/passwd" # Pathname:/etc/passwd
589 #
590 # This method doesn't access the file system; it is pure string manipulation.
591 #
592 def +(other)
593 other = Pathname.new(other) unless Pathname === other
594 Pathname.new(plus(@path, other.to_s))
595 end
597 def plus(path1, path2) # -> path
598 prefix2 = path2
599 index_list2 = []
600 basename_list2 = []
601 while r2 = chop_basename(prefix2)
602 prefix2, basename2 = r2
603 index_list2.unshift prefix2.length
604 basename_list2.unshift basename2
605 end
606 return path2 if prefix2 != ''
607 prefix1 = path1
608 while true
609 while !basename_list2.empty? && basename_list2.first == '.'
610 index_list2.shift
611 basename_list2.shift
612 end
613 break unless r1 = chop_basename(prefix1)
614 prefix1, basename1 = r1
615 next if basename1 == '.'
616 if basename1 == '..' || basename_list2.empty? || basename_list2.first != '..'
617 prefix1 = prefix1 + basename1
618 break
619 end
620 index_list2.shift
621 basename_list2.shift
622 end
623 r1 = chop_basename(prefix1)
624 if !r1 && /#{SEPARATOR_PAT}/o =~ File.basename(prefix1)
625 while !basename_list2.empty? && basename_list2.first == '..'
626 index_list2.shift
627 basename_list2.shift
628 end
629 end
630 if !basename_list2.empty?
631 suffix2 = path2[index_list2.first..-1]
632 r1 ? File.join(prefix1, suffix2) : prefix1 + suffix2
633 else
634 r1 ? prefix1 : File.dirname(prefix1)
635 end
636 end
637 private :plus
639 #
640 # Pathname#join joins pathnames.
641 #
642 # <tt>path0.join(path1, ..., pathN)</tt> is the same as
643 # <tt>path0 + path1 + ... + pathN</tt>.
644 #
645 def join(*args)
646 args.unshift self
647 result = args.pop
648 result = Pathname.new(result) unless Pathname === result
649 return result if result.absolute?
650 args.reverse_each {|arg|
651 arg = Pathname.new(arg) unless Pathname === arg
652 result = arg + result
653 return result if result.absolute?
654 }
655 result
656 end
658 #
659 # Returns the children of the directory (files and subdirectories, not
660 # recursive) as an array of Pathname objects. By default, the returned
661 # pathnames will have enough information to access the files. If you set
662 # +with_directory+ to +false+, then the returned pathnames will contain the
663 # filename only.
664 #
665 # For example:
666 # p = Pathname("/usr/lib/ruby/1.8")
667 # p.children
668 # # -> [ Pathname:/usr/lib/ruby/1.8/English.rb,
669 # Pathname:/usr/lib/ruby/1.8/Env.rb,
670 # Pathname:/usr/lib/ruby/1.8/abbrev.rb, ... ]
671 # p.children(false)
672 # # -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ]
673 #
674 # Note that the result never contain the entries <tt>.</tt> and <tt>..</tt> in
675 # the directory because they are not children.
676 #
677 # This method has existed since 1.8.1.
678 #
679 def children(with_directory=true)
680 with_directory = false if @path == '.'
681 result = []
682 Dir.foreach(@path) {|e|
683 next if e == '.' || e == '..'
684 if with_directory
685 result << self.class.new(File.join(@path, e))
686 else
687 result << self.class.new(e)
688 end
689 }
690 result
691 end
693 #
694 # #relative_path_from returns a relative path from the argument to the
695 # receiver. If +self+ is absolute, the argument must be absolute too. If
696 # +self+ is relative, the argument must be relative too.
697 #
698 # #relative_path_from doesn't access the filesystem. It assumes no symlinks.
699 #
700 # ArgumentError is raised when it cannot find a relative path.
701 #
702 # This method has existed since 1.8.1.
703 #
704 def relative_path_from(base_directory)
705 dest_directory = self.cleanpath.to_s
706 base_directory = base_directory.cleanpath.to_s
707 dest_prefix = dest_directory
708 dest_names = []
709 while r = chop_basename(dest_prefix)
710 dest_prefix, basename = r
711 dest_names.unshift basename if basename != '.'
712 end
713 base_prefix = base_directory
714 base_names = []
715 while r = chop_basename(base_prefix)
716 base_prefix, basename = r
717 base_names.unshift basename if basename != '.'
718 end
719 if dest_prefix != base_prefix
720 raise ArgumentError, "different prefix: #{dest_prefix.inspect} and #{base_directory.inspect}"
721 end
722 while !dest_names.empty? &&
723 !base_names.empty? &&
724 dest_names.first == base_names.first
725 dest_names.shift
726 base_names.shift
727 end
728 if base_names.include? '..'
729 raise ArgumentError, "base_directory has ..: #{base_directory.inspect}"
730 end
731 base_names.fill('..')
732 relpath_names = base_names + dest_names
733 if relpath_names.empty?
734 Pathname.new('.')
735 else
736 Pathname.new(File.join(*relpath_names))
737 end
738 end
739 end
741 class Pathname # * IO *
742 #
743 # #each_line iterates over the line in the file. It yields a String object
744 # for each line.
745 #
746 # This method has existed since 1.8.1.
747 #
748 def each_line(*args, &block) # :yield: line
749 IO.foreach(@path, *args, &block)
750 end
752 # Pathname#foreachline is *obsoleted* at 1.8.1. Use #each_line.
753 def foreachline(*args, &block)
754 warn "Pathname#foreachline is obsoleted. Use Pathname#each_line."
755 each_line(*args, &block)
756 end
758 # See <tt>IO.read</tt>. Returns all the bytes from the file, or the first +N+
759 # if specified.
760 def read(*args) IO.read(@path, *args) end
762 # See <tt>IO.readlines</tt>. Returns all the lines from the file.
763 def readlines(*args) IO.readlines(@path, *args) end
765 # See <tt>IO.sysopen</tt>.
766 def sysopen(*args) IO.sysopen(@path, *args) end
767 end
770 class Pathname # * File *
772 # See <tt>File.atime</tt>. Returns last access time.
773 def atime() File.atime(@path) end
775 # See <tt>File.ctime</tt>. Returns last (directory entry, not file) change time.
776 def ctime() File.ctime(@path) end
778 # See <tt>File.mtime</tt>. Returns last modification time.
779 def mtime() File.mtime(@path) end
781 # See <tt>File.chmod</tt>. Changes permissions.
782 def chmod(mode) File.chmod(mode, @path) end
784 # See <tt>File.lchmod</tt>.
785 def lchmod(mode) File.lchmod(mode, @path) end
787 # See <tt>File.chown</tt>. Change owner and group of file.
788 def chown(owner, group) File.chown(owner, group, @path) end
790 # See <tt>File.lchown</tt>.
791 def lchown(owner, group) File.lchown(owner, group, @path) end
793 # See <tt>File.fnmatch</tt>. Return +true+ if the receiver matches the given
794 # pattern.
795 def fnmatch(pattern, *args) File.fnmatch(pattern, @path, *args) end
797 # See <tt>File.fnmatch?</tt> (same as #fnmatch).
798 def fnmatch?(pattern, *args) File.fnmatch?(pattern, @path, *args) end
800 # See <tt>File.ftype</tt>. Returns "type" of file ("file", "directory",
801 # etc).
802 def ftype() File.ftype(@path) end
804 # See <tt>File.link</tt>. Creates a hard link.
805 def make_link(old) File.link(old, @path) end
807 # See <tt>File.open</tt>. Opens the file for reading or writing.
808 def open(*args, &block) # :yield: file
809 File.open(@path, *args, &block)
810 end
812 # See <tt>File.readlink</tt>. Read symbolic link.
813 def readlink() self.class.new(File.readlink(@path)) end
815 # See <tt>File.rename</tt>. Rename the file.
816 def rename(to) File.rename(@path, to) end
818 # See <tt>File.stat</tt>. Returns a <tt>File::Stat</tt> object.
819 def stat() File.stat(@path) end
821 # See <tt>File.lstat</tt>.
822 def lstat() File.lstat(@path) end
824 # See <tt>File.symlink</tt>. Creates a symbolic link.
825 def make_symlink(old) File.symlink(old, @path) end
827 # See <tt>File.truncate</tt>. Truncate the file to +length+ bytes.
828 def truncate(length) File.truncate(@path, length) end
830 # See <tt>File.utime</tt>. Update the access and modification times.
831 def utime(atime, mtime) File.utime(atime, mtime, @path) end
833 # See <tt>File.basename</tt>. Returns the last component of the path.
834 def basename(*args) self.class.new(File.basename(@path, *args)) end
836 # See <tt>File.dirname</tt>. Returns all but the last component of the path.
837 def dirname() self.class.new(File.dirname(@path)) end
839 # See <tt>File.extname</tt>. Returns the file's extension.
840 def extname() File.extname(@path) end
842 # See <tt>File.expand_path</tt>.
843 def expand_path(*args) self.class.new(File.expand_path(@path, *args)) end
845 # See <tt>File.split</tt>. Returns the #dirname and the #basename in an
846 # Array.
847 def split() File.split(@path).map {|f| self.class.new(f) } end
849 # Pathname#link is confusing and *obsoleted* because the receiver/argument
850 # order is inverted to corresponding system call.
851 def link(old)
852 warn 'Pathname#link is obsoleted. Use Pathname#make_link.'
853 File.link(old, @path)
854 end
856 # Pathname#symlink is confusing and *obsoleted* because the receiver/argument
857 # order is inverted to corresponding system call.
858 def symlink(old)
859 warn 'Pathname#symlink is obsoleted. Use Pathname#make_symlink.'
860 File.symlink(old, @path)
861 end
862 end
865 class Pathname # * FileTest *
867 # See <tt>FileTest.blockdev?</tt>.
868 def blockdev?() FileTest.blockdev?(@path) end
870 # See <tt>FileTest.chardev?</tt>.
871 def chardev?() FileTest.chardev?(@path) end
873 # See <tt>FileTest.executable?</tt>.
874 def executable?() FileTest.executable?(@path) end
876 # See <tt>FileTest.executable_real?</tt>.
877 def executable_real?() FileTest.executable_real?(@path) end
879 # See <tt>FileTest.exist?</tt>.
880 def exist?() FileTest.exist?(@path) end
882 # See <tt>FileTest.grpowned?</tt>.
883 def grpowned?() FileTest.grpowned?(@path) end
885 # See <tt>FileTest.directory?</tt>.
886 def directory?() FileTest.directory?(@path) end
888 # See <tt>FileTest.file?</tt>.
889 def file?() FileTest.file?(@path) end
891 # See <tt>FileTest.pipe?</tt>.
892 def pipe?() FileTest.pipe?(@path) end
894 # See <tt>FileTest.socket?</tt>.
895 def socket?() FileTest.socket?(@path) end
897 # See <tt>FileTest.owned?</tt>.
898 def owned?() FileTest.owned?(@path) end
900 # See <tt>FileTest.readable?</tt>.
901 def readable?() FileTest.readable?(@path) end
903 # See <tt>FileTest.world_readable?</tt>.
904 def world_readable?() FileTest.world_readable?(@path) end
906 # See <tt>FileTest.readable_real?</tt>.
907 def readable_real?() FileTest.readable_real?(@path) end
909 # See <tt>FileTest.setuid?</tt>.
910 def setuid?() FileTest.setuid?(@path) end
912 # See <tt>FileTest.setgid?</tt>.
913 def setgid?() FileTest.setgid?(@path) end
915 # See <tt>FileTest.size</tt>.
916 def size() FileTest.size(@path) end
918 # See <tt>FileTest.size?</tt>.
919 def size?() FileTest.size?(@path) end
921 # See <tt>FileTest.sticky?</tt>.
922 def sticky?() FileTest.sticky?(@path) end
924 # See <tt>FileTest.symlink?</tt>.
925 def symlink?() FileTest.symlink?(@path) end
927 # See <tt>FileTest.writable?</tt>.
928 def writable?() FileTest.writable?(@path) end
930 # See <tt>FileTest.world_writable?</tt>.
931 def world_writable?() FileTest.world_writable?(@path) end
933 # See <tt>FileTest.writable_real?</tt>.
934 def writable_real?() FileTest.writable_real?(@path) end
936 # See <tt>FileTest.zero?</tt>.
937 def zero?() FileTest.zero?(@path) end
938 end
941 class Pathname # * Dir *
942 # See <tt>Dir.glob</tt>. Returns or yields Pathname objects.
943 def Pathname.glob(*args) # :yield: p
944 if block_given?
945 Dir.glob(*args) {|f| yield self.new(f) }
946 else
947 Dir.glob(*args).map {|f| self.new(f) }
948 end
949 end
951 # See <tt>Dir.getwd</tt>. Returns the current working directory as a Pathname.
952 def Pathname.getwd() self.new(Dir.getwd) end
953 class << self; alias pwd getwd end
955 # Pathname#chdir is *obsoleted* at 1.8.1.
956 def chdir(&block)
957 warn "Pathname#chdir is obsoleted. Use Dir.chdir."
958 Dir.chdir(@path, &block)
959 end
961 # Pathname#chroot is *obsoleted* at 1.8.1.
962 def chroot
963 warn "Pathname#chroot is obsoleted. Use Dir.chroot."
964 Dir.chroot(@path)
965 end
967 # Return the entries (files and subdirectories) in the directory, each as a
968 # Pathname object.
969 def entries() Dir.entries(@path).map {|f| self.class.new(f) } end
971 # Iterates over the entries (files and subdirectories) in the directory. It
972 # yields a Pathname object for each entry.
973 #
974 # This method has existed since 1.8.1.
975 def each_entry(&block) # :yield: p
976 Dir.foreach(@path) {|f| yield self.class.new(f) }
977 end
979 # Pathname#dir_foreach is *obsoleted* at 1.8.1.
980 def dir_foreach(*args, &block)
981 warn "Pathname#dir_foreach is obsoleted. Use Pathname#each_entry."
982 each_entry(*args, &block)
983 end
985 # See <tt>Dir.mkdir</tt>. Create the referenced directory.
986 def mkdir(*args) Dir.mkdir(@path, *args) end
988 # See <tt>Dir.rmdir</tt>. Remove the referenced directory.
989 def rmdir() Dir.rmdir(@path) end
991 # See <tt>Dir.open</tt>.
992 def opendir(&block) # :yield: dir
993 Dir.open(@path, &block)
994 end
995 end
998 class Pathname # * Find *
999 #
1000 # Pathname#find is an iterator to traverse a directory tree in a depth first
1001 # manner. It yields a Pathname for each file under "this" directory.
1002 #
1003 # Since it is implemented by <tt>find.rb</tt>, <tt>Find.prune</tt> can be used
1004 # to control the traverse.
1005 #
1006 # If +self+ is <tt>.</tt>, yielded pathnames begin with a filename in the
1007 # current directory, not <tt>./</tt>.
1008 #
1009 def find(&block) # :yield: p
1010 require 'find'
1011 if @path == '.'
1012 Find.find(@path) {|f| yield self.class.new(f.sub(%r{\A\./}, '')) }
1013 else
1014 Find.find(@path) {|f| yield self.class.new(f) }
1015 end
1016 end
1017 end
1020 class Pathname # * FileUtils *
1021 # See <tt>FileUtils.mkpath</tt>. Creates a full path, including any
1022 # intermediate directories that don't yet exist.
1023 def mkpath
1024 require 'fileutils'
1025 FileUtils.mkpath(@path)
1026 nil
1027 end
1029 # See <tt>FileUtils.rm_r</tt>. Deletes a directory and all beneath it.
1030 def rmtree
1031 # The name "rmtree" is borrowed from File::Path of Perl.
1032 # File::Path provides "mkpath" and "rmtree".
1033 require 'fileutils'
1034 FileUtils.rm_r(@path)
1035 nil
1036 end
1037 end
1040 class Pathname # * mixed *
1041 # Removes a file or directory, using <tt>File.unlink</tt> or
1042 # <tt>Dir.unlink</tt> as necessary.
1043 def unlink()
1044 begin
1045 Dir.unlink @path
1046 rescue Errno::ENOTDIR
1047 File.unlink @path
1048 end
1049 end
1050 alias delete unlink
1052 # This method is *obsoleted* at 1.8.1. Use #each_line or #each_entry.
1053 def foreach(*args, &block)
1054 warn "Pathname#foreach is obsoleted. Use each_line or each_entry."
1055 if FileTest.directory? @path
1056 # For polymorphism between Dir.foreach and IO.foreach,
1057 # Pathname#foreach doesn't yield Pathname object.
1058 Dir.foreach(@path, *args, &block)
1059 else
1060 IO.foreach(@path, *args, &block)
1061 end
1062 end
1063 end
1065 module Kernel
1066 # create a pathname object.
1067 #
1068 # This method is available since 1.8.5.
1069 def Pathname(path) # :doc:
1070 Pathname.new(path)
1071 end
1072 private :Pathname
1073 end