Add glob filtering when listing directory entries

#KT-19192

libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt

@@ -278,38 +278,54 @@ public inline fun Path.isWritable(): Boolean = Files.isWritable(this)
 public inline fun Path.isSameFile(other: Path): Boolean = Files.isSameFile(this, other)
 
 /**
- * Return a list of the entries in this directory.
+ * Return a list of the entries in this directory optionally filtered by matching against the specified [glob] pattern.
  *
+ * @param glob the globbing pattern. The syntax is specified by the [FileSystem.getPathMatcher] method.
+ *
+ * @throws java.util.regex.PatternSyntaxException if the glob pattern is invalid.
  * @throws NotDirectoryException If this path does not refer to a directory
  * @throws IOException If an I/O error occurs
+ *
+ * @see Files.newDirectoryStream
  */
 @SinceKotlin("1.4")
 @ExperimentalPathApi
-public fun Path.listDirectoryEntries(): List<Path> {
-    return Files.newDirectoryStream(this).use { it.toList() }
+public fun Path.listDirectoryEntries(glob: String = "*"): List<Path> {
+    return Files.newDirectoryStream(this, glob).use { it.toList() }
 }
 
 /**
- * Call the [block] callback with a sequence of all entries in this directory.
+ * Call the [block] callback with a sequence of all entries in this directory
+ * optionally filtered by matching against the specified [glob] pattern.
  *
+ * @param glob the globbing pattern. The syntax is specified by the [FileSystem.getPathMatcher] method.
+ *
+ * @throws java.util.regex.PatternSyntaxException if the glob pattern is invalid.
  * @throws NotDirectoryException If this path does not refer to a directory
  * @throws IOException If an I/O error occurs
  * @return the value returned by [block]
+ *
+ * @see Files.newDirectoryStream
  */
 @SinceKotlin("1.4")
 @ExperimentalPathApi
-public fun <T> Path.useDirectoryEntries(block: (Sequence<Path>) -> T): T {
-    return Files.newDirectoryStream(this).use { block(it.asSequence()) }
+public fun <T> Path.useDirectoryEntries(glob: String = "*", block: (Sequence<Path>) -> T): T {
+    return Files.newDirectoryStream(this, glob).use { block(it.asSequence()) }
 }
 
 /**
- * Perform the given [action] on each entry in this directory.
+ * Perform the given [action] on each entry in this directory optionally filtered by matching against the specified [glob] pattern.
  *
+ * @param glob the globbing pattern. The syntax is specified by the [FileSystem.getPathMatcher] method.
+ *
+ * @throws java.util.regex.PatternSyntaxException if the glob pattern is invalid.
  * @throws NotDirectoryException If this path does not refer to a directory
  * @throws IOException If an I/O error occurs
+ *
+ * @see Files.newDirectoryStream
  */
 @SinceKotlin("1.4")
 @ExperimentalPathApi
-public fun Path.forEachDirectoryEntry(action: (Path) -> Unit) {
-    return Files.newDirectoryStream(this).use { it.forEach(action) }
+public fun Path.forEachDirectoryEntry(glob: String = "*", action: (Path) -> Unit) {
+    return Files.newDirectoryStream(this, glob).use { it.forEach(action) }
 }

libraries/stdlib/jdk7/test/PathExtensionsTest.kt

@@ -201,6 +201,9 @@ class PathExtensionsTest {
         Files.createFile(file)
         assertEquals(listOf(file), dir.listDirectoryEntries())
 
+        val fileTxt = createTempFile(dir, suffix = ".txt")
+        assertEquals(listOf(fileTxt), dir.listDirectoryEntries("*.txt"))
+
         assertFailsWith<NotDirectoryException> { file.listDirectoryEntries() }
     }
 
@@ -213,23 +216,25 @@ class PathExtensionsTest {
         Files.createFile(file)
         assertEquals(listOf(file), dir.useDirectoryEntries { it.toList() })
 
-        assertFailsWith<NotDirectoryException> { file.useDirectoryEntries { it.toList() } }
+        val fileTxt = createTempFile(dir, suffix = ".txt")
+        assertEquals(listOf(fileTxt), dir.useDirectoryEntries("*.txt") { it.toList() })
+
+        assertFailsWith<NotDirectoryException> { file.useDirectoryEntries { error("shouldn't get here") } }
     }
 
     @Test
     fun testForEachDirectoryEntry() {
         val dir = Files.createTempDirectory(null)
-        val entries = mutableListOf<Path>()
-
-        dir.forEachDirectoryEntry { entries.add(it) }
-        assertTrue(entries.isEmpty())
+        dir.forEachDirectoryEntry { error("shouldn't get here, but received $it") }
 
         val file = dir.resolve("f1")
         Files.createFile(file)
-        dir.forEachDirectoryEntry { entries.add(it) }
-        assertEquals(listOf(file), entries)
+        dir.forEachDirectoryEntry { assertEquals(file, it) }
 
-        assertFailsWith<NotDirectoryException> { file.forEachDirectoryEntry { } }
+        val fileTxt = createTempFile(dir, suffix = ".txt")
+        dir.forEachDirectoryEntry("*.txt") { assertEquals(fileTxt, it) }
+
+        assertFailsWith<NotDirectoryException> { file.forEachDirectoryEntry { error("shouldn't get here, but received $it") } }
     }