Warn when file() matches a collection of files (#5507)

---------

Signed-off-by: Ben Sherman <[email protected]>
Co-authored-by: Chris Hakkaart <[email protected]>

Author: bentsherman

docs/reference/stdlib-namespaces.md

@@ -56,8 +56,8 @@ The global namespace contains globally available constants and functions.
   :::
 : Stop the pipeline execution and return an exit code and optional error message.
 
-`file( filePattern: String, [options] ) -> Path | List<Path>`
-: Get a file from a file name or glob pattern. Returns a collection of files if the glob pattern yields zero or multiple files.
+`file( filePattern: String, [options] ) -> Path`
+: Get a file from a file name or glob pattern.
 
 : The following options are available:
 
@@ -79,10 +79,13 @@ The global namespace contains globally available constants and functions.
   `type: String`
   : Type of paths returned, can be `'file'`, `'dir'` or `'any'` (default: `'file'`)
 
-: See also: {ref}`channel.fromPath <channel-path>`.
+: :::{note}
+  This function returns a collection if the glob pattern yields zero or multiple files. Use `files()` to get a collection of files.
+  :::
 
 `files( filePattern: String, [options] ) -> List<Path>`
 : Get a collection of files from a file name or glob pattern. Supports the same options as `file()`.
+: See also: {ref}`channel.fromPath <channel-path>`.
 
 `groupKey( key, size: int ) -> GroupKey`
 : Create a grouping key to use with the {ref}`operator-grouptuple` operator.

modules/nextflow/src/main/groovy/nextflow/Nextflow.groovy

@@ -67,8 +67,7 @@ class Nextflow {
         return SysEnv.get(name)
     }
 
-    static private fileNamePattern( FilePatternSplitter splitter, Map opts ) {
-
+    private static List<Path> fileNamePattern( FilePatternSplitter splitter, Map opts ) {
         final scheme = splitter.scheme
         final target = scheme ? "$scheme://$splitter.parent" : splitter.parent
         final folder = toCanonicalPath(target)
@@ -77,15 +76,14 @@ class Nextflow {
         if( opts == null ) opts = [:]
         if( !opts.type ) opts.type = 'file'
 
-        def result = new LinkedList()
+        def result = new LinkedList<Path>()
         try {
             FileHelper.visitFiles(opts, folder, pattern) { Path it -> result.add(it) }
         }
         catch (NoSuchFileException e) {
             log.debug "No such file or directory: $folder -- Skipping visit"
         }
         return result
-
     }
 
     static private String str0(value) {
@@ -113,11 +111,16 @@ class Nextflow {
      * @param path A file path eventually including a glob pattern e.g. /some/path/file*.txt
      * @return An instance of {@link Path} when a single file is matched or a list of {@link Path}s
      */
-    static file( Map options = null, def filePattern ) {
-
+    static file(Map options = null, def filePattern) {
         if( !filePattern )
-            throw new IllegalArgumentException("Argument of `file` function cannot be ${filePattern==null?'null':'empty'}")
+            throw new IllegalArgumentException("Argument of `file()` function cannot be ${filePattern==null?'null':'empty'}")
+        final result = file0(options, filePattern)
+        if( result instanceof Collection && result.size() != 1 && NF.isSyntaxParserV2() )
+            log.warn "The `file()` function was called with a glob pattern that matched a collection of files -- use `files()` instead."
+        return result
+    }
 
+    private static file0( Map options = null, def filePattern ) {
         final path = filePattern as Path
         final glob = options?.containsKey('glob') ? options.glob as boolean : isGlobAllowed(path)
         if( !glob ) {
@@ -140,9 +143,11 @@ class Nextflow {
         return result
     }
 
-    static files( Map options=null, def path ) {
-        def result = file(options, path)
-        return result instanceof List ? result : [result]
+    static Collection<Path> files(Map options=null, def filePattern) {
+        if( !filePattern )
+            throw new IllegalArgumentException("Argument of `files()` function cannot be ${filePattern==null?'null':'empty'}")
+        final result = file0(options, filePattern)
+        return result instanceof Collection ? result : [result]
     }
 
 

modules/nextflow/src/test/groovy/nextflow/NextflowTest.groovy

@@ -85,13 +85,13 @@ class NextflowTest extends Specification {
         Nextflow.file(null)
         then:
         e = thrown(IllegalArgumentException)
-        e.message == 'Argument of `file` function cannot be null'
+        e.message == 'Argument of `file()` function cannot be null'
 
         when:
         Nextflow.file('')
         then:
         e = thrown(IllegalArgumentException)
-        e.message == 'Argument of `file` function cannot be empty'
+        e.message == 'Argument of `file()` function cannot be empty'
     }
 
     def 'should return http path' () {