From 5091b7a6092e9735b0400ff647f84f2e492c9576 Mon Sep 17 00:00:00 2001 From: itrujnara Date: Wed, 13 May 2026 11:29:19 +0200 Subject: [PATCH 01/10] feat(docs): add non-argument `val` channel inputs section to input/output options documentation --- .../components/modules/input-output-options.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index 40e652c84a..aefa3ba6df 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -50,6 +50,19 @@ When one and only one of multiple argument are required: ::: +## Non-argument `val` channel inputs + +Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool. + +- If a module implements multiple subcommands of a tool, the subcommand SHOULD be provided through a channel. +- If a module can output arbitrary or numerous file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT perform bespoke string manipulation on input paths. +:::info{title="Rationale" collapse} +Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour. +::: +- If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel. + +Non-standard `ext` fields (example: `ext.suffix`) SHOULD NOT be used to control module behaviour. + ## Output channel emissions Named file extensions MUST be emitted for ALL output channels. From a3c89dffd05deb8214edf53adb6effa6d77ff645 Mon Sep 17 00:00:00 2001 From: nf-core-bot Date: Wed, 13 May 2026 10:07:04 +0000 Subject: [PATCH 02/10] [automated] Fix code linting --- .../components/modules/input-output-options.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index aefa3ba6df..5d475513d5 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -56,9 +56,9 @@ Input channel `val` declarations MAY be used to control behaviours of the module - If a module implements multiple subcommands of a tool, the subcommand SHOULD be provided through a channel. - If a module can output arbitrary or numerous file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT perform bespoke string manipulation on input paths. -:::info{title="Rationale" collapse} -Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour. -::: + :::info{title="Rationale" collapse} + Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour. + ::: - If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel. Non-standard `ext` fields (example: `ext.suffix`) SHOULD NOT be used to control module behaviour. From 0b6d36f9fedbf9933a1a693d5c2e41772accb7c3 Mon Sep 17 00:00:00 2001 From: itrujnara Date: Wed, 13 May 2026 12:33:17 +0200 Subject: [PATCH 03/10] fix(docs): clarify usage of `val` inputs and subcommands in input/output options --- .../specifications/components/modules/input-output-options.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index 5d475513d5..f8f830a4d1 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -54,14 +54,13 @@ When one and only one of multiple argument are required: Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool. -- If a module implements multiple subcommands of a tool, the subcommand SHOULD be provided through a channel. - If a module can output arbitrary or numerous file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT perform bespoke string manipulation on input paths. :::info{title="Rationale" collapse} Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour. ::: - If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel. -Non-standard `ext` fields (example: `ext.suffix`) SHOULD NOT be used to control module behaviour. +Non-standard `ext` fields (example: `ext.suffix`) SHOULD NOT be used to control module behaviour. `val` inputs SHOULD NOT be used for subcommands, separate modules SHOULD be used instead. ## Output channel emissions From 93b093c2bac1fdd49dfc0c834a61407ee2d8c4fa Mon Sep 17 00:00:00 2001 From: itrujnara Date: Wed, 13 May 2026 14:09:02 +0200 Subject: [PATCH 04/10] feat(docs): enhance input/output options documentation with examples for `val` channel inputs --- .../modules/input-output-options.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index f8f830a4d1..60c6f773f0 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -57,8 +57,29 @@ Input channel `val` declarations MAY be used to control behaviours of the module - If a module can output arbitrary or numerous file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT perform bespoke string manipulation on input paths. :::info{title="Rationale" collapse} Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour. + + Example: + ```nextflow + # incorrect + out_file = "${prefix}.${in_file.name.split('.')[1]}.gz" + # correct + out_file = "${prefix}.${out_ext}.gz" + ``` ::: - If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel. + :::info{title="Example" collapse} + ```nextflow + input: + ... + val compress + + script: + compress_cmd = compress ? "gzip" : "cat" + """ + tool $in_file | $compress_cmd > $out_file + """ + ``` + ::: Non-standard `ext` fields (example: `ext.suffix`) SHOULD NOT be used to control module behaviour. `val` inputs SHOULD NOT be used for subcommands, separate modules SHOULD be used instead. From 443237e7e899932eab8044f85fc3fc458770f743 Mon Sep 17 00:00:00 2001 From: itrujnara Date: Wed, 13 May 2026 14:09:53 +0200 Subject: [PATCH 05/10] feat(docs): add example section for `val` channel inputs in input/output options documentation --- .../specifications/components/modules/input-output-options.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index 60c6f773f0..a351b05f9d 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -57,7 +57,9 @@ Input channel `val` declarations MAY be used to control behaviours of the module - If a module can output arbitrary or numerous file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT perform bespoke string manipulation on input paths. :::info{title="Rationale" collapse} Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour. + ::: + :::info{title="Example" collapse} Example: ```nextflow # incorrect From ee660ececcfe8b059e567b0e4f922e52c0e9bcaf Mon Sep 17 00:00:00 2001 From: nf-core-bot Date: Wed, 13 May 2026 12:16:44 +0000 Subject: [PATCH 06/10] [automated] Fix code linting --- .../components/modules/input-output-options.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index a351b05f9d..c07e094921 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -61,15 +61,19 @@ Input channel `val` declarations MAY be used to control behaviours of the module :::info{title="Example" collapse} Example: + ```nextflow # incorrect out_file = "${prefix}.${in_file.name.split('.')[1]}.gz" # correct out_file = "${prefix}.${out_ext}.gz" ``` + ::: + - If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel. :::info{title="Example" collapse} + ```nextflow input: ... @@ -81,6 +85,7 @@ Input channel `val` declarations MAY be used to control behaviours of the module tool $in_file | $compress_cmd > $out_file """ ``` + ::: Non-standard `ext` fields (example: `ext.suffix`) SHOULD NOT be used to control module behaviour. `val` inputs SHOULD NOT be used for subcommands, separate modules SHOULD be used instead. From 6f977eb54a34153e6bfd99a053d060ca74bae458 Mon Sep 17 00:00:00 2001 From: itrujnara Date: Wed, 13 May 2026 14:51:27 +0200 Subject: [PATCH 07/10] fix(docs): remove redundant example section heading from `val` channel inputs documentation --- .../specifications/components/modules/input-output-options.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index c07e094921..a5e9c0edb5 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -60,8 +60,6 @@ Input channel `val` declarations MAY be used to control behaviours of the module ::: :::info{title="Example" collapse} - Example: - ```nextflow # incorrect out_file = "${prefix}.${in_file.name.split('.')[1]}.gz" From e602cc280433fb6fb9126f4b08974cc19a10bff5 Mon Sep 17 00:00:00 2001 From: nf-core-bot Date: Wed, 13 May 2026 12:59:04 +0000 Subject: [PATCH 08/10] [automated] Fix code linting --- .../specifications/components/modules/input-output-options.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index a5e9c0edb5..70a18a09e4 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -60,6 +60,7 @@ Input channel `val` declarations MAY be used to control behaviours of the module ::: :::info{title="Example" collapse} + ```nextflow # incorrect out_file = "${prefix}.${in_file.name.split('.')[1]}.gz" From 7c918331a3ac75fa3f6a6f2b8c23c7d0d6b2f893 Mon Sep 17 00:00:00 2001 From: Igor Trujnara <53370556+itrujnara@users.noreply.github.com> Date: Mon, 18 May 2026 09:24:48 +0200 Subject: [PATCH 09/10] Apply suggestions from code review Co-authored-by: Matthieu Muffato --- .../components/modules/input-output-options.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index 70a18a09e4..11b14a0436 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -54,7 +54,7 @@ When one and only one of multiple argument are required: Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool. -- If a module can output arbitrary or numerous file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT perform bespoke string manipulation on input paths. +- If a module can output multiple file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT infer the output format from the input path. :::info{title="Rationale" collapse} Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour. ::: @@ -79,9 +79,9 @@ Input channel `val` declarations MAY be used to control behaviours of the module val compress script: - compress_cmd = compress ? "gzip" : "cat" + compress_cmd = compress ? "| gzip" : "" """ - tool $in_file | $compress_cmd > $out_file + tool $in_file $compress_cmd > $out_file """ ``` From 79ab1ee58684c444a9d608c159e6b78c412b38f0 Mon Sep 17 00:00:00 2001 From: itrujnara Date: Mon, 18 May 2026 10:10:29 +0200 Subject: [PATCH 10/10] fix(docs): clarify output format handling in `val` channel inputs documentation --- .../components/modules/input-output-options.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md index 11b14a0436..c9b6ebca1f 100644 --- a/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md +++ b/sites/docs/src/content/docs/specifications/components/modules/input-output-options.md @@ -54,7 +54,7 @@ When one and only one of multiple argument are required: Input channel `val` declarations MAY be used to control behaviours of the module that cannot be expressed with arguments of the underlying tool. -- If a module can output multiple file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT infer the output format from the input path. +- If a module can output multiple file formats, the output format SHOULD be provided through a channel. The module SHOULD NOT infer the output format from the input path. :::info{title="Rationale" collapse} Modules can encounter numerous input name scenarios. Custom string operations necessarily make assumptions about the name of the file (for example that the name of a compressed file has at least two dots). Providing an explicit format input returns full control to the pipeline developer and reduces the risk of unexpected behaviour. ::: @@ -70,6 +70,8 @@ Input channel `val` declarations MAY be used to control behaviours of the module ::: +- If the output format of a module is necessarily the same as the input format, the module MAY infer the output format from the input path. + - If a module contains an optional pipe (for example: compression, sorting), the pipe SHOULD be controlled with a Boolean input channel. :::info{title="Example" collapse} @@ -87,6 +89,8 @@ Input channel `val` declarations MAY be used to control behaviours of the module ::: +- If a module has an explicit output format, this format MAY be used to control compression. + Non-standard `ext` fields (example: `ext.suffix`) SHOULD NOT be used to control module behaviour. `val` inputs SHOULD NOT be used for subcommands, separate modules SHOULD be used instead. ## Output channel emissions