summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorgsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-01-20 15:17:13 +0000
committergsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-01-20 15:17:13 +0000
commit2f2a51a47b5998077e8d148850d5ac32b409f090 (patch)
treec488c54fc232878e30bf9c95601cadc1feaf7e89
parent7828a12f1971d5b722b717112b7f650d62bbc05e (diff)
Added RDoc comments.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@3378 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r--lib/find.rb53
1 files changed, 43 insertions, 10 deletions
diff --git a/lib/find.rb b/lib/find.rb
index 3c16533794c..9ca39cabcbc 100644
--- a/lib/find.rb
+++ b/lib/find.rb
@@ -1,16 +1,40 @@
-# Usage:
-# require "find"
#
-# Find.find('/foo','/bar') {|f| ...}
-# or
-# include Find
-# find('/foo','/bar') {|f| ...}
+# find.rb: the Find module for processing all files under a given directory.
#
+#
+# The +Find+ module supports the top-down traversal of a set of file paths.
+#
+# For example, to total the size of all files under your home directory,
+# ignoring anything in a "dot" directory (e.g. $HOME/.ssh):
+#
+# require 'find'
+#
+# total_size = 0
+#
+# Find.find(ENV["HOME"]) do |path|
+# if FileTest.directory?(path)
+# if File.basename(path)[0] == ?.
+# Find.prune # Don't look any further into this directory.
+# else
+# next
+# end
+# else
+# total_size += FileTest.size(path)
+# end
+# end
+#
module Find
- def find(*path)
- path.collect!{|d| d.dup}
- while file = path.shift
+
+ #
+ # Calls the associated block with the name of every file and directory listed
+ # as arguments, then recursively on their subdirectories, and so on.
+ #
+ # See the +Find+ module documentation for an example.
+ #
+ def find(*paths) # :yield: path
+ paths.collect!{|d| d.dup}
+ while file = paths.shift
catch(:prune) do
yield file
begin
@@ -26,7 +50,7 @@ module Find
else
f = File.join(file, f)
end
- path.unshift f
+ paths.unshift f
end
ensure
d.close
@@ -38,8 +62,17 @@ module Find
end
end
+ #
+ # Skips the current file or directory, restarting the loop with the next
+ # entry. If the current file is a directory, that directory will not be
+ # recursively entered. Meaningful only within the block associated with
+ # Find::find.
+ #
+ # See the +Find+ module documentation for an example.
+ #
def prune
throw :prune
end
+
module_function :find, :prune
end