file:descendants: recursion, filtering. qtspecs#2647

ChristianGruen · ChristianGruen · commit fb31a01ecb77 · 2026-07-08T08:10:59.000+02:00
diff --git a/basex-core/src/main/java/org/basex/query/func/Function.java b/basex-core/src/main/java/org/basex/query/func/Function.java
@@ -1495,8 +1495,8 @@ EMPTY_SEQUENCE_Z, flag(UPD), DB_URI),
   _FILE_DELETE(FileDelete::new, "delete(path[,recursive])",
       params(STRING_O, BOOLEAN_ZO), EMPTY_SEQUENCE_Z, flag(NDT), FILE_URI, Perm.ADMIN),
   /** XQuery function. */
-  _FILE_DESCENDANTS(FileDescendants::new, "descendants(dir)",
-      params(STRING_O), STRING_ZM, flag(NDT), FILE_URI, Perm.ADMIN),
+  _FILE_DESCENDANTS(FileDescendants::new, "descendants(dir[,options])",
+      params(STRING_O, MAP_ZO), STRING_ZM, flag(NDT, HOF), FILE_URI, Perm.ADMIN),
   /** XQuery function. */
   _FILE_DIR_SEPARATOR(FileDirSeparator::new, "dir-separator()",
       params(), STRING_O, FILE_URI),
diff --git a/basex-core/src/main/java/org/basex/query/func/file/FileChildren.java b/basex-core/src/main/java/org/basex/query/func/file/FileChildren.java
@@ -3,7 +3,11 @@
 import java.io.*;
 
 import org.basex.query.*;
+import org.basex.query.func.*;
 import org.basex.query.value.*;
+import org.basex.query.value.item.*;
+import org.basex.query.value.seq.*;
+import org.basex.util.list.*;
 
 /**
  * Function implementation.
@@ -14,6 +18,10 @@
 public final class FileChildren extends FileList {
   @Override
   public Value eval(final QueryContext qc) throws QueryException, IOException {
-    return paths(false, qc);
+    final TokenList tl = new TokenList();
+    final FItem recurse = constantFn(false), filter = constantFn(true);
+    list(toPath(arg(0), qc), recurse, new HofArgs(1), null, -1,
+        filter, new HofArgs(1), tl, Integer.MAX_VALUE, true, qc);
+    return StrSeq.get(tl);
   }
 }
diff --git a/basex-core/src/main/java/org/basex/query/func/file/FileDescendants.java b/basex-core/src/main/java/org/basex/query/func/file/FileDescendants.java
@@ -1,9 +1,16 @@
 package org.basex.query.func.file;
 
 import java.io.*;
+import java.nio.file.*;
 
 import org.basex.query.*;
+import org.basex.query.func.*;
 import org.basex.query.value.*;
+import org.basex.query.value.item.*;
+import org.basex.query.value.seq.*;
+import org.basex.query.value.type.*;
+import org.basex.util.list.*;
+import org.basex.util.options.*;
 
 /**
  * Function implementation.
@@ -12,8 +19,37 @@
  * @author Christian Gruen
  */
 public final class FileDescendants extends FileList {
+  /** Descendants options. */
+  public static class DescendantsOptions extends Options {
+    /** Option: filter. */
+    public static final ValueOption FILTER = new ValueOption("filter", Types.FUNCTION_O);
+    /** Option: recurse. */
+    public static final ValueOption RECURSE = new ValueOption("recurse", Types.FUNCTION_O);
+    /** Option: maximum recursion depth. */
+    public static final NumberOption DEPTH = new NumberOption("depth");
+  }
+
   @Override
   public Value eval(final QueryContext qc) throws QueryException, IOException {
-    return paths(true, qc);
+    final Path dir = toPath(arg(0), qc);
+    final DescendantsOptions options = toOptions(arg(1), new DescendantsOptions(), qc);
+
+    final Value filterValue = options.get(DescendantsOptions.FILTER);
+    final Value recurseValue = options.get(DescendantsOptions.RECURSE);
+    final Integer depth = options.get(DescendantsOptions.DEPTH);
+    final FItem filter = filterValue.isEmpty() ? constantFn(true) :
+        toFunction(filterValue, 1, qc);
+    final FItem recurse = recurseValue.isEmpty() ? constantFn(true) :
+        toFunction(recurseValue, 1, qc);
+
+    final TokenList list = new TokenList();
+    list(dir, recurse, new HofArgs(1), null, -1, filter, new HofArgs(1), list,
+        depth != null ? depth : Integer.MAX_VALUE, true, qc);
+    return StrSeq.get(list);
+  }
+
+  @Override
+  public int hofOffsets() {
+    return functionOption(1) ? Integer.MAX_VALUE : 0;
   }
 }
diff --git a/basex-core/src/main/java/org/basex/query/func/file/FileList.java b/basex-core/src/main/java/org/basex/query/func/file/FileList.java
@@ -3,13 +3,17 @@
 import java.io.*;
 import java.nio.file.*;
 import java.util.*;
-import java.util.function.*;
 import java.util.regex.*;
 
 import org.basex.io.*;
 import org.basex.query.*;
+import org.basex.query.func.*;
+import org.basex.query.util.list.*;
 import org.basex.query.value.*;
+import org.basex.query.value.item.*;
 import org.basex.query.value.seq.*;
+import org.basex.query.value.type.*;
+import org.basex.query.var.*;
 import org.basex.util.*;
 import org.basex.util.list.*;
 
@@ -29,44 +33,32 @@ public Value eval(final QueryContext qc) throws QueryException, IOException {
     final Pattern pttrn = pattern == null ? null :
       Pattern.compile(IOFile.regex(pattern, false), Prop.CASE ? 0 : Pattern.CASE_INSENSITIVE);
     final TokenList tl = new TokenList();
-    list(dir, recursive, pttrn, tl, dir.getNameCount(), qc);
-    return StrSeq.get(tl);
-  }
-
-  /**
-   * Returns full file paths.
-   * @param recursive recursive flag
-   * @param qc query context
-   * @return file paths
-   * @throws QueryException query exception
-   * @throws IOException I/O exception
-   */
-  Value paths(final boolean recursive, final QueryContext qc) throws QueryException, IOException {
-    final TokenList tl = new TokenList();
-    list(toPath(arg(0), qc), recursive, null, tl, -1, qc);
+    final FItem recurse = constantFn(recursive), filter = constantFn(true);
+    list(dir, recurse, new HofArgs(1), pttrn, dir.getNameCount(),
+        filter, new HofArgs(1), tl, Integer.MAX_VALUE, true, qc);
     return StrSeq.get(tl);
   }
 
   /**
    * Collects the subdirectories and files of the specified directory.
    * @param root root path
-   * @param recursive recursive flag
+   * @param recurse subtree predicate
+   * @param recurseArgs arguments for the subtree predicate
    * @param pattern file name pattern; ignored if {@code null}
+   * @param index index of root path for relative paths; {@code -1} for absolute paths
+   * @param filter inclusion predicate
+   * @param filterArgs arguments for the inclusion predicate
    * @param list file list
-   * @param index index of root path
+   * @param depth maximum number of subdirectory levels to descend ({@code 0}: none)
+   * @param top {@code true} on the initial call (errors will be propagated)
    * @param qc query context
+   * @throws QueryException query exception
    * @throws IOException I/O exception
    */
-  private static void list(final Path root, final boolean recursive, final Pattern pattern,
-      final TokenList list, final int index, final QueryContext qc) throws IOException {
-
-    // filter function for adding results
-    final BiConsumer<Path, Boolean> add = (child, dir) -> {
-      if(pattern == null || pattern.matcher(child.getFileName().toString()).matches()) {
-        final Path path = index < 0 ? child : child.subpath(index, child.getNameCount());
-        list.add(get(path, dir).string());
-      }
-    };
+  final void list(final Path root, final FItem recurse, final HofArgs recurseArgs,
+      final Pattern pattern, final int index, final FItem filter, final HofArgs filterArgs,
+      final TokenList list, final int depth, final boolean top, final QueryContext qc)
+      throws QueryException, IOException {
 
     // collect directories and files first (reduces number of open directory streams)
     final ArrayList<Path> dirs = new ArrayList<>(), files = new ArrayList<>();
@@ -77,24 +69,73 @@ private static void list(final Path root, final boolean recursive, final Pattern
       }
     } catch(final IOException ex) {
       // skip entries that cannot be accessed; throw exception only on root level
-      if(index == -1 || index == root.getNameCount()) {
+      if(top) {
         Util.debug(ex);
         throw ex;
       }
+      return;
     }
 
     // add directories
-    for(final Path dir : dirs) {
-      add.accept(dir, true);
-      // recursive traversal: do not follow links
-      if(recursive && !Files.isSymbolicLink(dir)) {
-        list(dir, true, pattern, list, index == -1 ? -2 : index, qc);
+    for(final Path child : dirs) {
+      final Str path = add(child, true, pattern, filter, filterArgs, index, list, qc);
+      // recursive traversal: descend if the depth allows it, do not follow links
+      if(depth > 0 && !Files.isSymbolicLink(child)) {
+        final Str p = path != null ? path : get(subPath(child, index), true);
+        if(test(recurse, recurseArgs.set(0, p), qc)) {
+          list(child, recurse, recurseArgs, pattern, index, filter, filterArgs,
+              list, depth - 1, false, qc);
+        }
       }
     }
 
     // add files
-    for(final Path file : files) {
-      add.accept(file, false);
+    for(final Path child : files) {
+      add(child, false, pattern, filter, filterArgs, index, list, qc);
     }
   }
+
+  /**
+   * Adds an entry to the result list, applying pattern and filter checks.
+   * @param child raw path
+   * @param isDir directory flag
+   * @param pattern file name pattern (can be {@code null})
+   * @param filter inclusion predicate
+   * @param filterArgs arguments for the inclusion predicate
+   * @param index index of root path (or {@code -1})
+   * @param list file list
+   * @param qc query context
+   * @return display path, or {@code null} if the pattern excluded the entry
+   * @throws QueryException query exception
+   */
+  private Str add(final Path child, final boolean isDir, final Pattern pattern,
+      final FItem filter, final HofArgs filterArgs, final int index, final TokenList list,
+      final QueryContext qc) throws QueryException {
+    // pattern check (operates on the file name)
+    if(pattern != null && !pattern.matcher(child.getFileName().toString()).matches()) return null;
+
+    final Str path = get(subPath(child, index), isDir);
+    if(test(filter, filterArgs.set(0, path), qc)) list.add(path.string());
+    return path;
+  }
+
+  /**
+   * Returns the effective result path.
+   * @param child raw path
+   * @param index index of root path for relative paths; {@code -1} for absolute paths
+   * @return display path
+   */
+  private static Path subPath(final Path child, final int index) {
+    return index < 0 ? child : child.subpath(index, child.getNameCount());
+  }
+
+  /**
+   * Creates a boolean predicate function.
+   * @param value return value
+   * @return function item
+   */
+  final FItem constantFn(final boolean value) {
+    return new FuncItem(info, Bln.get(value), new Var[0], AnnList.EMPTY,
+      FuncType.get(Types.BOOLEAN_O), 0, null);
+  }
 }
diff --git a/basex-core/src/test/java/org/basex/query/func/FileModuleTest.java b/basex-core/src/test/java/org/basex/query/func/FileModuleTest.java
@@ -228,6 +228,47 @@ public final class FileModuleTest extends SandboxTest {
     error(func.args(PATH3), FILE_NO_DIR_X);
     error(func.args(PATH3 + NAME), FILE_NOT_FOUND_X);
     contains(func.args(PATH1), "x");
+
+    // build a fresh tree for option-based tests: PATH1/x/y/file.txt
+    query(_FILE_DELETE.args(PATH3));
+    query(_FILE_CREATE_DIR.args(PATH4));
+    query(_FILE_WRITE.args(PATH4 + "/file.txt", "abcd"));
+
+    // default: three entries (x/, x/y/, x/y/file.txt)
+    query("count(" + func.args(PATH1) + ")", 3);
+
+    // filter: include only the .txt file
+    final String filterTxt = " { 'filter': fn($p) { ends-with($p, '.txt') } }";
+    query("count(" + func.args(PATH1, filterTxt) + ")", 1);
+    contains(func.args(PATH1, filterTxt), "file.txt");
+
+    // recurse: prune the 'x' subtree -> only x/ itself is returned
+    final String prune = " { 'recurse': fn($d) "
+        + "{ not(ends-with($d, 'x' || file:dir-separator())) } }";
+    query("count(" + func.args(PATH1, prune) + ")", 1);
+
+    // combined: prune ahead of filter -> empty result
+    final String both = " { 'filter': fn($p) { ends-with($p, '.txt') }, "
+        + "'recurse': fn($d) { not(ends-with($d, 'x' || file:dir-separator())) } }";
+    query("count(" + func.args(PATH1, both) + ")", 0);
+
+    // empty options map: equivalent to no options
+    query("count(" + func.args(PATH1, " {}") + ")", 3);
+
+    // empty sequence as predicate result: treated as false
+    query("count(" + func.args(PATH1, " { 'filter': fn($p) { () } }") + ")", 0);
+    query("count(" + func.args(PATH1, " { 'recurse': fn($d) { () } }") + ")", 1);
+
+    // depth: limit the number of subdirectory levels that are traversed
+    query("count(" + func.args(PATH1, " { 'depth': 0 }") + ")", 1);
+    query("count(" + func.args(PATH1, " { 'depth': 1 }") + ")", 2);
+    query("count(" + func.args(PATH1, " { 'depth': 2 }") + ")", 3);
+    // depth combined with filter: the .txt file lies below the depth limit
+    query("count(" + func.args(PATH1,
+        " { 'depth': 1, 'filter': fn($p) { ends-with($p, '.txt') } }") + ")", 0);
+
+    // unknown option
+    error(func.args(PATH1, " { 'unknown': true() }"), INVALIDOPTION_X);
   }
 
   /** Test method. */
