Allow fgbio tools to access meta information about themselves.

This allows SAM program records to be created.

Author: nh13

src/main/scala/com/fulcrumgenomics/cmdline/FgBioMain.scala

@@ -28,13 +28,12 @@ import java.io.IOException
 import java.net.InetAddress
 import java.nio.file.Paths
 import java.text.DecimalFormat
-
 import com.fulcrumgenomics.bam.api.{SamSource, SamWriter}
 import com.fulcrumgenomics.cmdline.FgBioMain.FailureException
 import com.fulcrumgenomics.commons.CommonsDef._
 import com.fulcrumgenomics.commons.util.SystemUtil.IntelCompressionLibrarySupported
 import com.fulcrumgenomics.commons.util.{LazyLogging, LogLevel, Logger}
-import com.fulcrumgenomics.sopt.cmdline.CommandLineProgramParserStrings
+import com.fulcrumgenomics.sopt.cmdline.{CommandLineParser, CommandLineProgramParserStrings}
 import com.fulcrumgenomics.sopt.{Sopt, arg}
 import com.fulcrumgenomics.util.Io
 import com.fulcrumgenomics.vcf.api.VcfWriter
@@ -110,16 +109,27 @@ class FgBioMain extends LazyLogging {
     }
 
     val startTime = System.currentTimeMillis()
-    val exit      = Sopt.parseCommandAndSubCommand[FgBioCommonArgs,FgBioTool](name, args.toIndexedSeq, Sopt.find[FgBioTool](packageList)) match {
+    val parser    = new CommandLineParser[FgBioTool](name)  // Keep a reference to the parser so we can get the command line
+    val exit      = parser.parseCommandAndSubCommand[FgBioCommonArgs](args.toIndexedSeq, Sopt.find[FgBioTool](packageList)) match {
       case Sopt.Failure(usage) =>
         System.err.print(usage())
         1
-      case Sopt.CommandSuccess(cmd) =>
+      case Sopt.CommandSuccess(_) =>
         unreachable("CommandSuccess should never be returned by parseCommandAndSubCommand.")
       case Sopt.SubcommandSuccess(commonArgs, subcommand) =>
         FgBioCommonArgs.args = commonArgs
         val name = subcommand.getClass.getSimpleName
         try {
+          parser.commandLine.foreach { commandLine =>
+            parser.genericClpNameOnCommandLine
+            subcommand.toolInfo = FgBioToolInfo(
+              name                    = name,
+              args                    = this.name +: args.toIndexedSeq, // make sure to include the tool set name
+              commandLineWithDefaults = commandLine,
+              description             = parser.formatShortDescription(Sopt.inspect(subcommand.getClass).description),
+              version                 = subcommand.getClass.getPackage.getImplementationVersion
+            )
+          }
           printStartupLines(name, args, commonArgs)
           subcommand.execute()
           printEndingLines(startTime, name, true)
@@ -152,7 +162,6 @@ class FgBioMain extends LazyLogging {
 
   /** Prints a line of useful information when a tool starts executing. */
   protected def printStartupLines(tool: String, args: Array[String], commonArgs: FgBioCommonArgs): Unit = {
-    val version    = CommandLineProgramParserStrings.version(getClass, color=false).replace("Version: ", "")
     val host       = try { InetAddress.getLocalHost.getHostName } catch { case _: Exception => "unknown-host" }
     val user       = System.getProperty("user.name")
     val jreVersion = System.getProperty("java.runtime.version")
@@ -172,4 +181,6 @@ class FgBioMain extends LazyLogging {
 
   /** The packages we wish to include in our command line **/
   protected def packageList: List[String] = List[String]("com.fulcrumgenomics")
+
+  private def version: String = CommandLineProgramParserStrings.version(getClass, color=false).replace("Version: ", "")
 }

src/main/scala/com/fulcrumgenomics/cmdline/FgBioTool.scala

@@ -26,9 +26,51 @@ package com.fulcrumgenomics.cmdline
 import com.fulcrumgenomics.cmdline.FgBioMain.FailureException
 import com.fulcrumgenomics.commons.util.LazyLogging
 import com.fulcrumgenomics.sopt.cmdline.ValidationException
+import com.fulcrumgenomics.util.Metric
+import htsjdk.samtools.{SAMFileHeader, SAMProgramRecord}
+
+import scala.annotation.tailrec
+
+/** Stores meta information about the command line use to invoke a tool.
+  *
+  * @param name the name of the tool.
+  * @param args the list of arguments as given on the command line; this will contain any arguments also given to
+  *             [[FgBioMain]] in [[FgBioCommonArgs]].
+  * @param commandLineWithDefaults the command line as given to the tool, along with the defaults for all other
+  *              arguments.  This will include arguments given to [[FgBioMain]] in [[FgBioCommonArgs]].
+  * @param description the description of the tool
+  * @param version the version of the tool.
+  */
+case class FgBioToolInfo(name: String, args: Seq[String], commandLineWithDefaults: String, description: String, version: String) extends Metric {
+
+  /** The command line as given to the tool, without any defaults added.  This will include arguments given to
+    * [[FgBioMain]] in [[FgBioCommonArgs]].*/
+  def commandLineWithoutDefaults: String = args.mkString(" ")
+
+  /** Adds a program group to the SAMFileHeader returning the ID. */
+  def addProgramGroupTo(header: SAMFileHeader, id: Option[String]=None): SAMProgramRecord = {
+    // Get the id
+    val pgId = id.getOrElse {
+      @tailrec
+      def getPgId(intId: Int): String = if (header.getProgramRecord(intId.toString) == null) intId.toString else getPgId(intId + 1)
+      getPgId(1)
+    }
+    val pg = new SAMProgramRecord(pgId)
+    pg.setProgramName(name)
+    pg.setCommandLine(commandLineWithDefaults)
+    pg.setProgramVersion(version)
+    header.addProgramRecord(pg)
+    pg
+  }
+}
+
 
 /** All fgbio tools should extend this. */
 trait FgBioTool extends LazyLogging {
+  /** Meta information about the command line use to invoke this tool, or [[None]] if unset. */
+  private var _toolInfo: Option[FgBioToolInfo] = None
+
+  /** All tools should implement this method. */
   def execute(): Unit
 
   /** Fail with just an exit code. */
@@ -45,4 +87,10 @@ trait FgBioTool extends LazyLogging {
 
   /** Generates a validation exception if the test value is false. */
   def validate(test: Boolean, message: => String) = if (!test) throw new ValidationException(message)
+
+  /** Meta information about the command line use to invoke this tool, or [[None]] if unset. */
+  def toolInfo: Option[FgBioToolInfo] = _toolInfo
+
+  /** Sets the command line used to invoke this tool. */
+  private[cmdline] def toolInfo_=(commandLine: FgBioToolInfo): Unit = this._toolInfo = Some(commandLine)
 }

src/test/scala/com/fulcrumgenomics/cmdline/ClpTests.scala

@@ -26,14 +26,18 @@ package com.fulcrumgenomics.cmdline
 
 import com.fulcrumgenomics.sopt.{arg, clp}
 import com.fulcrumgenomics.testing.UnitSpec
+import com.fulcrumgenomics.util.Metric
+
+import java.nio.file.Path
 
 /* Tis a silly CLP. */
 @clp(group=ClpGroups.Utilities, description="A test class")
 class TestClp
 (
   @arg(flag='e', doc="If set, exit with this code.")    val exitCode: Option[Int],
   @arg(flag='m', doc="If set, fail with this message.") val message: Option[String],
-  @arg(flag='p', doc="Print this message.")             val printMe: Option[String]
+  @arg(flag='p', doc="Print this message.")             val printMe: Option[String],
+  @arg(flag='i', doc="Write the tool information.")     val infoPath: Option[Path] = None
 ) extends FgBioTool {
   override def execute(): Unit = {
     (exitCode, message) match {
@@ -42,6 +46,9 @@ class TestClp
       case (None,     Some(msg)) => fail(msg)
       case (None,     None     ) => printMe.foreach(println)
     }
+    this.infoPath.foreach { path =>
+      this.toolInfo.foreach { info => Metric.write(path, info) }
+    }
   }
 }
 
@@ -61,4 +68,32 @@ class ClpTests extends UnitSpec {
   it should "fail and print usage" in {
     new FgBioMain().makeItSo("SomeProgram --with-args=that-dont-exist".split(' ')) should not be 0
   }
+
+  it should "provide command line information to the tool" in {
+    val tmpPath = makeTempFile("tool_info.", ".tab")
+    new FgBioMain().makeItSo(args=s"--async-io true TestClp -i $tmpPath".split(' ')) shouldBe 0
+    val metrics = Metric.read[FgBioToolInfo](tmpPath)
+    metrics should have length 1
+    val metric = metrics.head
+
+    // args/commandLineWithoutDefaults
+    metric.commandLineWithDefaults should include ("fgbio --async-io true") // argument set _prior_ to the tool name
+    metric.commandLineWithDefaults should not include ("fgbio --compression 5") // default argument _prior_ to the tool name
+    metric.commandLineWithoutDefaults should include ("TestClp")
+    metric.commandLineWithoutDefaults should include (s"-i $tmpPath")
+    metric.commandLineWithoutDefaults should not include ("--print-me :none:") // a default argument
+
+    // commandLineWithDefaults
+    metric.commandLineWithDefaults should include ("fgbio --async-io true") // argument set _prior_ to the tool name
+    metric.commandLineWithDefaults should include (" --compression 5") // default argument _prior_ to the tool namee
+    metric.commandLineWithDefaults should include ("TestClp")
+    metric.commandLineWithDefaults should include (s"--info-path $tmpPath")
+    metric.commandLineWithDefaults should include ("--print-me :none:") // a default argument
+
+    // description
+    metric.description shouldBe "A test class"
+
+    // version
+    //metric.version shouldBe "null" // not set in scalatest
+  }
 }