groovy git commit: GROOVY-8341: GDK: eachDirRecurse and eachFileRecurse are NOT depth-first - clarify wording in javadoc (closes #614)

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

groovy git commit: GROOVY-8341: GDK: eachDirRecurse and eachFileRecurse are NOT depth-first - clarify wording in javadoc (closes #614)

paulk
Repository: groovy
Updated Branches:
  refs/heads/GROOVY_2_4_X 37a8ef920 -> 00b3161dd


GROOVY-8341: GDK: eachDirRecurse and eachFileRecurse are NOT depth-first - clarify wording in javadoc (closes #614)


Project: http://git-wip-us.apache.org/repos/asf/groovy/repo
Commit: http://git-wip-us.apache.org/repos/asf/groovy/commit/00b3161d
Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/00b3161d
Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/00b3161d

Branch: refs/heads/GROOVY_2_4_X
Commit: 00b3161ddb3923178a7a28d5e33637e7eb3e5db1
Parents: 37a8ef9
Author: paulk <[hidden email]>
Authored: Mon Oct 9 21:21:52 2017 +1000
Committer: paulk <[hidden email]>
Committed: Thu Oct 12 13:17:19 2017 +1000

----------------------------------------------------------------------
 .../groovy/runtime/ResourceGroovyMethods.java   | 61 +++++++++++---------
 .../groovy/runtime/NioGroovyMethods.java        | 59 ++++++++++---------
 2 files changed, 65 insertions(+), 55 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/groovy/blob/00b3161d/src/main/org/codehaus/groovy/runtime/ResourceGroovyMethods.java
----------------------------------------------------------------------
diff --git a/src/main/org/codehaus/groovy/runtime/ResourceGroovyMethods.java b/src/main/org/codehaus/groovy/runtime/ResourceGroovyMethods.java
index 9ec2660..7d85f61 100644
--- a/src/main/org/codehaus/groovy/runtime/ResourceGroovyMethods.java
+++ b/src/main/org/codehaus/groovy/runtime/ResourceGroovyMethods.java
@@ -1050,7 +1050,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * Both regular files and subfolders/subdirectories can be processed depending
      * on the fileType enum value.
      *
-     * @param self     a file object
+     * @param self     a File (that happens to be a folder/directory)
      * @param fileType if normal files or directories or both should be processed
      * @param closure  the closure to invoke
      * @throws FileNotFoundException    if the given directory does not exist
@@ -1077,7 +1077,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * Both regular files and subfolders/subdirectories are processed.
      *
      * @param self    a File (that happens to be a folder/directory)
-     * @param closure a closure (first parameter is the 'child' file)
+     * @param closure a closure (the parameter passed is the 'child' file)
      * @throws FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided File object does not represent a directory
      * @see java.io.File#listFiles()
@@ -1093,7 +1093,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * ignoring regular files.
      *
      * @param self    a File (that happens to be a folder/directory)
-     * @param closure a closure (first parameter is the subdirectory file)
+     * @param closure a closure (the parameter passed is the subdirectory file)
      * @throws FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided File object does not represent a directory
      * @see java.io.File#listFiles()
@@ -1105,12 +1105,13 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes the closure for each descendant file in this directory.
-     * Sub-directories are recursively searched in a depth-first fashion.
-     * Both regular files and subdirectories may be passed to the closure
-     * depending on the value of fileType.
+     * Processes each descendant file in this directory and any sub-directories.
+     * Processing consists of potentially calling <code>closure</code> passing it the current
+     * file (which may be a normal file or subdirectory) and then if a subdirectory was encountered,
+     * recursively processing the subdirectory. Whether the closure is called is determined by whether
+     * the file was a normal file or subdirectory and the value of fileType.
      *
-     * @param self     a file object
+     * @param self     a File (that happens to be a folder/directory)
      * @param fileType if normal files or directories or both should be processed
      * @param closure  the closure to invoke on each file
      * @throws FileNotFoundException    if the given directory does not exist
@@ -1134,8 +1135,11 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes <code>closure</code> for each descendant file in this directory tree.
-     * Sub-directories are recursively traversed as found.
+     * Processes each descendant file in this directory and any sub-directories.
+     * Processing consists of potentially calling <code>closure</code> passing it the current
+     * file (which may be a normal file or subdirectory) and then if a subdirectory was encountered,
+     * recursively processing the subdirectory.
+     *
      * The traversal can be adapted by providing various options in the <code>options</code> Map according
      * to the following keys:<dl>
      * <dt>type</dt><dd>A {@link groovy.io.FileType} enum to determine if normal files or directories or both are processed</dd>
@@ -1143,7 +1147,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * which can be used to control subsequent processing.</dd>
      * <dt>preRoot</dt><dd>A boolean indicating that the 'preDir' closure should be applied at the root level</dd>
      * <dt>postDir</dt><dd>A {@link groovy.lang.Closure} run after each directory is processed and optionally returning a {@link groovy.io.FileVisitResult} value
-     * which can be used to control subsequent processing.</dd>
+     * which can be used to control subsequent processing. Particularly useful when strict depth-first traversal is required.</dd>
      * <dt>postRoot</dt><dd>A boolean indicating that the 'postDir' closure should be applied at the root level</dd>
      * <dt>visitRoot</dt><dd>A boolean indicating that the given closure should be applied for the root dir
      * (not applicable if the 'type' is set to {@link groovy.io.FileType#FILES})</dd>
@@ -1178,7 +1182,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * ) {it -> totalSize += it.size(); count++ }
      * </pre>
      *
-     * @param self    a File
+     * @param self    a File (that happens to be a folder/directory)
      * @param options a Map of options to alter the traversal behavior
      * @param closure the Closure to invoke on each file/directory and optionally returning a {@link groovy.io.FileVisitResult} value
      *                which can be used to control subsequent processing
@@ -1254,12 +1258,11 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes the closure for each descendant file in this directory tree.
-     * Sub-directories are recursively traversed in a depth-first fashion.
+     * Processes each descendant file in this directory and any sub-directories.
      * Convenience method for {@link #traverse(java.io.File, java.util.Map, groovy.lang.Closure)} when
      * no options to alter the traversal behavior are required.
      *
-     * @param self    a File
+     * @param self    a File (that happens to be a folder/directory)
      * @param closure the Closure to invoke on each file/directory and optionally returning a {@link groovy.io.FileVisitResult} value
      *                which can be used to control subsequent processing
      * @throws FileNotFoundException    if the given directory does not exist
@@ -1278,7 +1281,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * for {@link #traverse(java.io.File, java.util.Map, groovy.lang.Closure)} allowing the 'visit' closure
      * to be included in the options Map rather than as a parameter.
      *
-     * @param self    a File
+     * @param self    a File (that happens to be a folder/directory)
      * @param options a Map of options to alter the traversal behavior
      * @throws FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided File object does not represent a directory or illegal filter combinations are supplied
@@ -1348,12 +1351,13 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes the closure for each descendant file in this directory.
-     * Sub-directories are recursively searched in a depth-first fashion.
-     * Both regular files and subdirectories are passed to the closure.
+     * Processes each descendant file in this directory and any sub-directories.
+     * Processing consists of calling <code>closure</code> passing it the current
+     * file (which may be a normal file or subdirectory) and then if a subdirectory was encountered,
+     * recursively processing the subdirectory.
      *
-     * @param self    a File
-     * @param closure a closure
+     * @param self    a File (that happens to be a folder/directory)
+     * @param closure a Closure
      * @throws FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided File object does not represent a directory
      * @see #eachFileRecurse(java.io.File, groovy.io.FileType, groovy.lang.Closure)
@@ -1364,11 +1368,12 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes the closure for each descendant directory of this directory.
-     * Sub-directories are recursively searched in a depth-first fashion.
-     * Only subdirectories are passed to the closure; regular files are ignored.
+     * Recursively processes each descendant subdirectory in this directory.
+     * Processing consists of calling <code>closure</code> passing it the current
+     * subdirectory and then recursively processing that subdirectory.
+     * Regular files are ignored during traversal.
      *
-     * @param self    a directory
+     * @param self    a File (that happens to be a folder/directory)
      * @param closure a closure
      * @throws FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided File object does not represent a directory
@@ -1399,7 +1404,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * baseDir.eachFileMatch FILES, { new File(baseDir, it).size() > 4096 }, { println "$it.name ${it.size()}" }
      * </pre>
      *
-     * @param self       a file
+     * @param self       a File (that happens to be a folder/directory)
      * @param fileType   whether normal files or directories or both should be processed
      * @param nameFilter the filter to perform on the name of the file/directory (using the {@link DefaultGroovyMethods#isCase(java.lang.Object, java.lang.Object)} method)
      * @param closure    the closure to invoke
@@ -1430,7 +1435,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * with different kinds of filters like regular expressions, classes, ranges etc.
      * Both regular files and subdirectories are matched.
      *
-     * @param self       a file
+     * @param self       a File (that happens to be a folder/directory)
      * @param nameFilter the nameFilter to perform on the name of the file (using the {@link DefaultGroovyMethods#isCase(java.lang.Object, java.lang.Object)} method)
      * @param closure    the closure to invoke
      * @throws FileNotFoundException    if the given directory does not exist
@@ -1449,7 +1454,7 @@ public class ResourceGroovyMethods extends DefaultGroovyMethodsSupport {
      * with different kinds of filters like regular expressions, classes, ranges etc.
      * Only subdirectories are matched; regular files are ignored.
      *
-     * @param self       a file
+     * @param self       a File (that happens to be a folder/directory)
      * @param nameFilter the nameFilter to perform on the name of the directory (using the {@link DefaultGroovyMethods#isCase(java.lang.Object, java.lang.Object)} method)
      * @param closure    the closure to invoke
      * @throws FileNotFoundException    if the given directory does not exist

http://git-wip-us.apache.org/repos/asf/groovy/blob/00b3161d/subprojects/groovy-nio/src/main/java/org/codehaus/groovy/runtime/NioGroovyMethods.java
----------------------------------------------------------------------
diff --git a/subprojects/groovy-nio/src/main/java/org/codehaus/groovy/runtime/NioGroovyMethods.java b/subprojects/groovy-nio/src/main/java/org/codehaus/groovy/runtime/NioGroovyMethods.java
index 46fecdf..9089234 100644
--- a/subprojects/groovy-nio/src/main/java/org/codehaus/groovy/runtime/NioGroovyMethods.java
+++ b/subprojects/groovy-nio/src/main/java/org/codehaus/groovy/runtime/NioGroovyMethods.java
@@ -760,7 +760,7 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
      * Both regular files and subfolders/subdirectories can be processed depending
      * on the fileType enum value.
      *
-     * @param self     a file object
+     * @param self     a Path (that happens to be a folder/directory)
      * @param fileType if normal files or directories or both should be processed
      * @param closure  the closure to invoke
      * @throws java.io.FileNotFoundException    if the given directory does not exist
@@ -788,7 +788,7 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
      * Both regular files and subfolders/subdirectories are processed.
      *
      * @param self    a Path (that happens to be a folder/directory)
-     * @param closure a closure (first parameter is the 'child' file)
+     * @param closure a closure (the parameter is the Path for the 'child' file)
      * @throws java.io.FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided Path object does not represent a directory
      * @see #eachFile(Path, groovy.io.FileType, groovy.lang.Closure)
@@ -803,7 +803,7 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
      * ignoring regular files.
      *
      * @param self    a Path (that happens to be a folder/directory)
-     * @param closure a closure (first parameter is the subdirectory file)
+     * @param closure a closure (the parameter is the Path for the subdirectory file)
      * @throws java.io.FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided Path object does not represent a directory
      * @see #eachFile(Path, groovy.io.FileType, groovy.lang.Closure)
@@ -814,12 +814,13 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes the closure for each descendant file in this directory.
-     * Sub-directories are recursively searched in a depth-first fashion.
-     * Both regular files and subdirectories may be passed to the closure
-     * depending on the value of fileType.
+     * Processes each descendant file in this directory and any sub-directories.
+     * Processing consists of potentially calling <code>closure</code> passing it the current
+     * file (which may be a normal file or subdirectory) and then if a subdirectory was encountered,
+     * recursively processing the subdirectory. Whether the closure is called is determined by whether
+     * the file was a normal file or subdirectory and the value of fileType.
      *
-     * @param self     a file object
+     * @param self     a Path (that happens to be a folder/directory)
      * @param fileType if normal files or directories or both should be processed
      * @param closure  the closure to invoke on each file
      * @throws java.io.FileNotFoundException    if the given directory does not exist
@@ -842,8 +843,11 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes <code>closure</code> for each descendant file in this directory tree.
-     * Sub-directories are recursively traversed as found.
+     * Processes each descendant file in this directory and any sub-directories.
+     * Processing consists of potentially calling <code>closure</code> passing it the current
+     * file (which may be a normal file or subdirectory) and then if a subdirectory was encountered,
+     * recursively processing the subdirectory.
+     *
      * The traversal can be adapted by providing various options in the <code>options</code> Map according
      * to the following keys:<dl>
      * <dt>type</dt><dd>A {@link groovy.io.FileType} enum to determine if normal files or directories or both are processed</dd>
@@ -886,7 +890,7 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
      * ) {it -> totalSize += it.size(); count++ }
      * </pre>
      *
-     * @param self    a Path
+     * @param self    a Path (that happens to be a folder/directory)
      * @param options a Map of options to alter the traversal behavior
      * @param closure the Closure to invoke on each file/directory and optionally returning a {@link groovy.io.FileVisitResult} value
      *                which can be used to control subsequent processing
@@ -963,12 +967,11 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes the closure for each descendant file in this directory tree.
-     * Sub-directories are recursively traversed in a depth-first fashion.
+     * Processes each descendant file in this directory and any sub-directories.
      * Convenience method for {@link #traverse(Path, java.util.Map, groovy.lang.Closure)} when
      * no options to alter the traversal behavior are required.
      *
-     * @param self    a Path
+     * @param self    a Path (that happens to be a folder/directory)
      * @param closure the Closure to invoke on each file/directory and optionally returning a {@link groovy.io.FileVisitResult} value
      *                which can be used to control subsequent processing
      * @throws java.io.FileNotFoundException    if the given directory does not exist
@@ -987,7 +990,7 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
      * for {@link #traverse(Path, java.util.Map, groovy.lang.Closure)} allowing the 'visit' closure
      * to be included in the options Map rather than as a parameter.
      *
-     * @param self    a Path
+     * @param self    a Path (that happens to be a folder/directory)
      * @param options a Map of options to alter the traversal behavior
      * @throws java.io.FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided Path object does not represent a directory or illegal filter combinations are supplied
@@ -1062,12 +1065,13 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes the closure for each descendant file in this directory.
-     * Sub-directories are recursively searched in a depth-first fashion.
-     * Both regular files and subdirectories are passed to the closure.
+     * Processes each descendant file in this directory and any sub-directories.
+     * Processing consists of calling <code>closure</code> passing it the current
+     * file (which may be a normal file or subdirectory) and then if a subdirectory was encountered,
+     * recursively processing the subdirectory.
      *
-     * @param self    a Path
-     * @param closure a closure
+     * @param self    a Path (that happens to be a folder/directory)
+     * @param closure a Closure
      * @throws java.io.FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided Path object does not represent a directory
      * @see #eachFileRecurse(Path, groovy.io.FileType, groovy.lang.Closure)
@@ -1078,11 +1082,12 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
     }
 
     /**
-     * Invokes the closure for each descendant directory of this directory.
-     * Sub-directories are recursively searched in a depth-first fashion.
-     * Only subdirectories are passed to the closure; regular files are ignored.
+     * Recursively processes each descendant subdirectory in this directory.
+     * Processing consists of calling <code>closure</code> passing it the current
+     * subdirectory and then recursively processing that subdirectory.
+     * Regular files are ignored during traversal.
      *
-     * @param self    a directory
+     * @param self    a Path (that happens to be a folder/directory)
      * @param closure a closure
      * @throws java.io.FileNotFoundException    if the given directory does not exist
      * @throws IllegalArgumentException if the provided Path object does not represent a directory
@@ -1113,7 +1118,7 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
      * baseDir.eachFileMatch FILES, { new Path(baseDir, it).size() > 4096 }, { println "$it.name ${it.size()}" }
      * </pre>
      *
-     * @param self       a file
+     * @param self       a Path (that happens to be a folder/directory)
      * @param fileType   whether normal files or directories or both should be processed
      * @param nameFilter the filter to perform on the name of the file/directory (using the {@link org.codehaus.groovy.runtime.DefaultGroovyMethods#isCase(Object, Object)} method)
      * @param closure    the closure to invoke
@@ -1144,7 +1149,7 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
      * with different kinds of filters like regular expressions, classes, ranges etc.
      * Both regular files and subdirectories are matched.
      *
-     * @param self       a file
+     * @param self       a Path (that happens to be a folder/directory)
      * @param nameFilter the nameFilter to perform on the name of the file (using the {@link org.codehaus.groovy.runtime.DefaultGroovyMethods#isCase(Object, Object)} method)
      * @param closure    the closure to invoke
      * @throws java.io.FileNotFoundException    if the given directory does not exist
@@ -1163,7 +1168,7 @@ public class NioGroovyMethods extends DefaultGroovyMethodsSupport {
      * with different kinds of filters like regular expressions, classes, ranges etc.
      * Only subdirectories are matched; regular files are ignored.
      *
-     * @param self       a file
+     * @param self       a Path (that happens to be a folder/directory)
      * @param nameFilter the nameFilter to perform on the name of the directory (using the {@link org.codehaus.groovy.runtime.DefaultGroovyMethods#isCase(Object, Object)} method)
      * @param closure    the closure to invoke
      * @throws java.io.FileNotFoundException    if the given directory does not exist