add --- parameter to component help messages

CHANGELOG.md

@@ -19,6 +19,8 @@ TODO add summary
   The biggest change is how the exporting of the schema is done, but this has no impact on the user.
   However, switching to Scala 3 allows for additional features and improvements in the future.
 
+* `--help`: Component `--help` messages will now display what built in `---` options are available (PR #784).
+
 ## BUG FIXES
 
 * `config build`: Fix a bug where a missing main script would cause a stack trace instead of a proper error message (PR #776).

src/main/scala/io/viash/runners/ExecutableRunner.scala

@@ -165,6 +165,12 @@ final case class ExecutableRunner(
         |            shift 1
         |            ;;""".stripMargin
 
+    val helpStrings = 
+      s"""Viash built in Engines:
+         |    ---engine=ENGINE_ID
+         |        Specify the engine to use. Options are: ${engines.map(_.id).mkString(", ")}.
+         |        Default: ${engines.head.id}""".stripMargin
+
     val typeSetterStrs = engines.groupBy(_.`type`).map{ case (engineType, engineList) => 
       s""" ${oneOfEngines(engineList)} ; then
         |  VIASH_ENGINE_TYPE='${engineType}'""".stripMargin
@@ -179,6 +185,7 @@ final case class ExecutableRunner(
 
     BashWrapperMods(
       preParse = preParse,
+      helpStrings = List(("Engine", helpStrings)),
       parsers = parsers,
       postParse = postParse
     )
@@ -337,6 +344,20 @@ final case class ExecutableRunner(
         |            shift 1
         |            ;;""".stripMargin
 
+    val helpStrings = 
+      s"""Viash built in Docker:
+         |    ---setup=STRATEGY
+         |        Setup the docker container. Options are: alwaysbuild, alwayscachedbuild, ifneedbebuild, ifneedbecachedbuild, alwayspull, alwayspullelsebuild, alwayspullelsecachedbuild, ifneedbepull, ifneedbepullelsebuild, ifneedbepullelsecachedbuild, push, pushifnotpresent, donothing.
+         |        Default: ifneedbepullelsecachedbuild
+         |    ---dockerfile
+         |        Print the dockerfile to stdout.
+         |    ---docker_run_args=ARG
+         |        Provide runtime arguments to Docker. See the documentation on `docker run` for more information.
+         |    ---docker_image_id
+         |        Print the docker image id to stdout.
+         |    ---debug
+         |        Enter the docker container for debugging purposes.""".stripMargin
+
     val setDockerImageId = engines.map { engine => 
       s"""[[ "$$VIASH_ENGINE_ID" == '${engine.id}' ]]; then
         |    VIASH_DOCKER_IMAGE_ID='${engine.getTargetIdentifier(config).toString()}'""".stripMargin  
@@ -382,6 +403,7 @@ final case class ExecutableRunner(
 
     BashWrapperMods(
       preParse = preParse,
+      helpStrings = List(("Docker", helpStrings)),
       parsers = parsers,
       postParse = postParse
     )

src/main/scala/io/viash/wrapper/BashWrapper.scala

@@ -102,6 +102,19 @@ object BashWrapper {
     }
   }
 
+  def generateHelp(helpSections: List[(String, String)]): String = {
+    val sections = helpSections.sortBy(_._1).map(_._2)
+    val helpStr = joinSections(sections).split("\n")
+      .map(h => Bash.escapeString(h, quote = true))
+      .mkString("  echo \"", "\"\n  echo \"", "\"")
+    val functionStr =
+      s"""# ViashHelp: Display helpful explanation about this executable
+      |function ViashHelp {
+      |$helpStr
+      |}""".stripMargin
+    spaceCode(functionStr)
+  }
+
   /**
     * Joins multiple strings such that there are two spaces between them.
     *
@@ -284,6 +297,7 @@ object BashWrapper {
        |VIASH_META_TEMP_DIR="$$VIASH_TEMP"
        |
        |${spaceCode(allMods.preParse)}
+       |${generateHelp(allMods.helpStrings)}
        |# initialise array
        |VIASH_POSITIONAL_ARGS=''
        |
@@ -336,18 +350,8 @@ object BashWrapper {
 
 
   private def generateHelp(config: Config) = {
-    val help = Helper.generateHelp(config)
-    val helpStr = help
-      .map(h => Bash.escapeString(h, quote = true))
-      .mkString("  echo \"", "\"\n  echo \"", "\"")
-
-    val preParse =
-      s"""# ViashHelp: Display helpful explanation about this executable
-      |function ViashHelp {
-      |$helpStr
-      |}""".stripMargin
-
-    BashWrapperMods(preParse = preParse)
+    val help = Helper.generateHelp(config).mkString("\n")
+    BashWrapperMods(helpStrings = List(("", help)))
   }
 
   private def generateParsers(params: List[Argument[_]]) = {
@@ -723,6 +727,15 @@ object BashWrapper {
 
 
   private def generateComputationalRequirements(config: Config) = {
+
+    val helpStrings = 
+      """Viash built in Computational Requirements:
+        |    ---cpus=INT
+        |        Number of CPUs to use
+        |    ---memory=STRING
+        |        Amount of memory to use
+        |""".stripMargin
+
     val compArgs = List(
       ("---cpus", "VIASH_META_CPUS", config.requirements.cpus.map(_.toString)),
       ("---memory", "VIASH_META_MEMORY", config.requirements.memoryAsBytes.map(_.toString + "b"))
@@ -801,6 +814,7 @@ object BashWrapper {
 
     // return output
     BashWrapperMods(
+      helpStrings = List(("Computational Requirements", helpStrings)),
       parsers = parsers,
       postParse = BashWrapper.joinSections(List(defaultsStrs, memoryCalculations))
     )

src/main/scala/io/viash/wrapper/BashWrapperMods.scala

@@ -21,6 +21,7 @@ import io.viash.config.arguments.Argument
 
 case class BashWrapperMods(
   preParse: String = "",
+  helpStrings: List[(String, String)] = Nil,
   parsers: String = "",
   postParse: String = "",
   preRun: String = "",
@@ -31,6 +32,7 @@ case class BashWrapperMods(
   def `++`(other: BashWrapperMods): BashWrapperMods = {
     BashWrapperMods(
       preParse = BashWrapper.joinSections(List(preParse, other.preParse)),
+      helpStrings = helpStrings ++ other.helpStrings,
       parsers = BashWrapper.joinSections(List(parsers, other.parsers), middle = "\n"),
       postParse = BashWrapper.joinSections(List(postParse, other.postParse)),
       preRun = BashWrapper.joinSections(List(preRun, other.preRun)),

src/test/scala/io/viash/runners/nextflow/Vdsl3ModuleTest.scala

@@ -105,11 +105,16 @@ class Vdsl3ModuleTest extends AnyFunSuite with BeforeAndAfterAll {
       "run", workflowsPath + "/pipeline3/config.vsh.yaml",
       "--", "--help"
     )
+
+    // explicitly remove triple dash parameters
+    // these make sense when running from command line, not when running in nextflow
+    val correctedTestOutput = testOutput.stdout.replaceAll("""\n\nViash built in .*(\n\s{4}---.*\n(\s{8}.*)+)*""", "")
+
 
     assert(testOutput.exitCode == Some(0))
 
     // check if they are the same
-    assert(correctedStdOut2 == testOutput.stdout)
+    assert(correctedStdOut2 == correctedTestOutput)
   }
 
   override def afterAll(): Unit = {