Merge pull request #44 from nextflow-io/feat/summary-text

`beforeText` and `afterText` for summary logs + color filter

Author: nvnieuwk

CHANGELOG.md

@@ -11,6 +11,7 @@
 1. The plugin now fully supports nested parameters!
 2. Added a config option `validation.parametersSchema` which can be used to set the parameters JSON schema in a config file. The default is `nextflow_schema.json`
 3. The parameter summary log will now automatically show nested parameters.
+4. Added two new configuration options: `validation.summary.beforeText` and `validation.summary.afterText` to automatically add some text before and after the output of the `paramsSummaryLog()` function. The colors from these texts will be automatically filtered out if `validation.monochromeLogs` is set to `true`.
 
 ## Help message changes
 
@@ -21,9 +22,9 @@
    - `validation.help.fullParameter`: The parameter to use for the expanded help message. This help message will show all parameters no matter how deeply nested they are. Default = `helpFull`
    - `validation.help.showHiddenParameter`: The parameter to use to also show all parameters with the `hidden: true` keyword in the schema. Default = `showHidden`
    - `validation.help.showHidden`: Set this to `true` to show hidden parameters by default. This configuration option is overwritten by the value supplied to the parameter in `validation.help.showHiddenParameter`. Default = `false`
-   - `validation.help.beforeText`: Some custom text to add before the help message.
-   - `validation.help.afterText`: Some custom text to add after the help message.
-   - `validation.help.command`: An example command to add to the top of the help message
+   - `validation.help.beforeText`: Some custom text to add before the help message. The colors from this text will be automatically filtered out if `validation.monochromeLogs` is set to `true`.
+   - `validation.help.afterText`: Some custom text to add after the help message. The colors from this text will be automatically filtered out if `validation.monochromeLogs` is set to `true`.
+   - `validation.help.command`: An example command to add to the top of the help message. The colors from this text will be automatically filtered out if `validation.monochromeLogs` is set to `true`.
 3. Added support for nested parameters to the help message. A detailed help message using `--help <parameter>` will now also contain all nested parameters. The parameter supplied to `--help` can be a nested parameter too (e.g. `--help top_parameter.nested_parameter.deeper_parameter`)
 4. The help message now won't show empty parameter groups.
 5. The help message will now automatically contain the three parameters used to get help messages.

docs/configuration/configuration.md

@@ -148,6 +148,10 @@ Any string provided to this option will printed before the help message.
 validation.help.beforeText = "Running pipeline version 1.0" // default: ""
 ```
 
+!!! info
+
+    All color values (like `\033[0;31m`, which means the color red) will be filtered out when `validation.monochromeLogs` is set to `true`
+
 ### command
 
 !!! example "This option does not affect the help message created by the `paramsHelp()` function"
@@ -166,6 +170,10 @@ Typical pipeline command:
   nextflow run main.nf --input samplesheet.csv --outdir output
 ```
 
+!!! info
+
+    All color values (like `\033[0;31m`, which means the color red) will be filtered out when `validation.monochromeLogs` is set to `true`
+
 ### afterText
 
 !!! example "This option does not affect the help message created by the `paramsHelp()` function"
@@ -175,3 +183,37 @@ Any string provided to this option will be printed after the help message.
 ```groovy
 validation.help.afterText = "Please cite the pipeline owners when using this pipeline" // default: ""
 ```
+
+!!! info
+
+    All color values (like `\033[0;31m`, which means the color red) will be filtered out when `validation.monochromeLogs` is set to `true`
+
+## Summary
+
+The `validation.summary` config scope can be used to configure the output of the `paramsSummaryLog()` function.
+
+This scope contains the following options:
+
+### beforeText
+
+Any string provided to this option will printed before the parameters log message.
+
+```groovy
+validation.summary.beforeText = "Running pipeline version 1.0" // default: ""
+```
+
+!!! info
+
+    All color values (like `\033[0;31m`, which means the color red) will be filtered out when `validation.monochromeLogs` is set to `true`
+
+### afterText
+
+Any string provided to this option will be printed after the parameters log message.
+
+```groovy
+validation.summary.afterText = "Please cite the pipeline owners when using this pipeline" // default: ""
+```
+
+!!! info
+
+    All color values (like `\033[0;31m`, which means the color red) will be filtered out when `validation.monochromeLogs` is set to `true`

plugins/nf-schema/src/main/nextflow/validation/SchemaValidator.groovy

@@ -500,6 +500,7 @@ Please contact the pipeline maintainer(s) if you see this warning as a user.
 
         def colors = Utils.logColours(config.monochromeLogs)
         String output  = ''
+        output += config.summary.beforeText
         def Map paramsMap = paramsSummaryMap(workflow, parameters_schema: schemaFilename)
         paramsMap.each { key, value ->
             paramsMap[key] = flattenNestedParamsMap(value as Map)
@@ -517,6 +518,7 @@ Please contact the pipeline maintainer(s) if you see this warning as a user.
         }
         output += "!! Only displaying parameters that differ from the pipeline defaults !!\n"
         output += "-${colors.dim}----------------------------------------------------${colors.reset}-"
+        output += config.summary.afterText
         return output
     }
 

plugins/nf-schema/src/main/nextflow/validation/Utils.groovy

@@ -270,6 +270,16 @@ public class Utils {
         return colorcodes
     }
 
+    public static String removeColors(String input) {
+        if (!input) {return input}
+        String output = input
+        List colors = logColours(false).collect { it.value }
+        colors.each { color ->
+            output = output.replace(color, "")
+        }
+        return output
+    }
+
     //
     // This function tries to read a JSON params file
     //

plugins/nf-schema/src/main/nextflow/validation/config/HelpConfig.groovy

@@ -26,15 +26,21 @@ class HelpConfig {
     final public String  command
     final public Boolean showHidden
 
-    HelpConfig(Map map, Map params) {
+    HelpConfig(Map map, Map params, Boolean monochromeLogs) {
         def config = map ?: Collections.emptyMap()
         enabled             = config.enabled                    ?: false
         shortParameter      = config.shortParameter             ?: "help"
         fullParameter       = config.fullParameter              ?: "helpFull"
         showHiddenParameter = config.showHiddenParameter        ?: "showHidden"
-        beforeText          = config.beforeText                 ?: ""
-        afterText           = config.afterText                  ?: ""
-        command             = config.command                    ?: ""
+        if (monochromeLogs) {
+            beforeText  = config.beforeText ? Utils.removeColors(config.beforeText): ""
+            afterText   = config.afterText  ? Utils.removeColors(config.afterText) : ""
+            command     = config.command    ? Utils.removeColors(config.command)   : ""
+        } else {
+            beforeText  = config.beforeText ?: ""
+            afterText   = config.afterText  ?: ""
+            command     = config.command    ?: ""
+        }
         showHidden          = params.get(showHiddenParameter)   ?: config.showHidden    ?: false
     }
 }

plugins/nf-schema/src/main/nextflow/validation/config/SummaryConfig.groovy

@@ -0,0 +1,33 @@
+package nextflow.validation
+
+import groovy.util.logging.Slf4j
+import groovy.transform.PackageScope
+
+
+/**
+ * This class allows to model a specific configuration, extracting values from a map and converting
+ *
+ * We anotate this class as @PackageScope to restrict the access of their methods only to class in the
+ * same package
+ *
+ * @author : nvnieuwk <[email protected]>
+ *
+ */
+
+@Slf4j
+@PackageScope
+class SummaryConfig {
+    final public String beforeText
+    final public String afterText
+
+    SummaryConfig(Map map, Boolean monochromeLogs) {
+        def config = map ?: Collections.emptyMap()
+        if (monochromeLogs) {
+            beforeText  = config.beforeText ? Utils.removeColors(config.beforeText): ""
+            afterText   = config.afterText  ? Utils.removeColors(config.afterText) : ""
+        } else {
+            beforeText  = config.beforeText ?: ""
+            afterText   = config.afterText  ?: ""
+        }
+    }
+}

plugins/nf-schema/src/main/nextflow/validation/config/ValidationConfig.groovy

@@ -24,6 +24,7 @@ class ValidationConfig {
     final public String  parametersSchema
     final public Boolean showHiddenParams = false
     final public HelpConfig help
+    final public SummaryConfig summary
 
     final public List<String> ignoreParams
 
@@ -36,7 +37,8 @@ class ValidationConfig {
             log.warn("configuration option `validation.showHiddenParams` is deprecated, please use `validation.help.showHidden` or the `--showHidden` parameter instead")
         }
         parametersSchema        = config.parametersSchema       ?: "nextflow_schema.json"
-        help                    = new HelpConfig(config.help as Map ?: [:], params)
+        help                    = new HelpConfig(config.help as Map ?: [:], params, monochromeLogs)
+        summary                 = new SummaryConfig(config.summary as Map ?: [:], monochromeLogs)
 
         if(config.ignoreParams && !(config.ignoreParams instanceof List<String>)) {
             throw new SchemaValidationException("Config value 'validation.ignoreParams' should be a list of String values")
@@ -47,6 +49,4 @@ class ValidationConfig {
         }
         ignoreParams += config.defaultIgnoreParams ?: []
     }
-
-    String getPrefix() { prefix }
 }

plugins/nf-schema/src/test/nextflow/validation/ParamsSummaryLogTest.groovy

@@ -138,4 +138,50 @@ class ParamsSummaryLogTest extends Dsl2Spec{
         stdout.size() == 11
         stdout ==~ /.*\[0;34mthis.is.so.deep: .\[0;32mchanged_value.*/
     }
+
+    def 'should print params summary - adds before and after text' () {
+        given:
+        def schema = Path.of('src/testResources/nextflow_schema.json').toAbsolutePath().toString()
+        def  SCRIPT = """
+            params.outdir = "outDir"
+            include { paramsSummaryLog } from 'plugin/nf-schema'
+            
+            def summary_params = paramsSummaryLog(workflow, parameters_schema: '$schema')
+            log.info summary_params
+        """
+
+        when:
+        def config = [
+            "validation": [
+                "summary": [
+                    "beforeText": "This text is printed before \n",
+                    "afterText": "\nThis text is printed after",
+                ]
+            ]
+        ]
+        def result = new MockScriptRunner(config).setScript(SCRIPT).execute()
+        def stdout = capture
+                .toString()
+                .readLines()
+                .findResults { !it.contains("DEBUG") && !it.contains("after]]") ? it : null }
+                .findResults {it.contains('Only displaying parameters that differ from the pipeline defaults') ||
+                    it.contains('Core Nextflow options') ||
+                    it.contains('runName') ||
+                    it.contains('launchDir') ||
+                    it.contains('workDir') ||
+                    it.contains('projectDir') ||
+                    it.contains('userName') ||
+                    it.contains('profile') ||
+                    it.contains('configFiles') ||
+                    it.contains('Input/output options') ||
+                    it.contains('outdir') ||
+                    it.contains('This text is printed before') ||
+                    it.contains('This text is printed after')
+                    ? it : null }
+        
+        then:
+        noExceptionThrown()
+        stdout.size() == 13
+        stdout ==~ /.*\[0;34moutdir     : .\[0;32moutDir.*/
+    }
 }