fix #29; subcommand --help doesn't show global options (#119)

Author: nitely

.gitignore

@@ -6,3 +6,4 @@ build/
 vendor/
 tests/test_all
 tests/test_nested_cmd
+tests/test_help

confutils.nim

@@ -317,51 +317,47 @@ type
     defaultCmdOpts
     conditionalOpts
 
-proc describeOptions(help: var string,
-                     cmd: CmdInfo, cmdInvocation: string,
-                     appInfo: HelpAppInfo, optionsType = normalOpts) =
-  if cmd.hasOpts:
-    case optionsType
-    of normalOpts:
-      helpOutput "\pThe following options are available:\p\p"
-    of conditionalOpts:
-      helpOutput ", the following additional options are available:\p\p"
-    of defaultCmdOpts:
-      discard
-
-    for opt in cmd.opts:
-      if opt.kind == Arg or
-         opt.kind == Discriminator or
-         opt.isHidden: continue
-
-      if opt.separator.len > 0:
-        helpOutput opt.separator
-        helpOutput "\p"
+proc describeOptionsList(
+  help: var string,
+  cmd: CmdInfo,
+  appInfo: HelpAppInfo
+) =
+  for opt in cmd.opts:
+    if opt.kind == Arg or
+        opt.kind == Discriminator or
+        opt.isHidden:
+      continue
 
-      # Indent all command-line switches
-      helpOutput " "
+    if opt.separator.len > 0:
+      helpOutput opt.separator
+      helpOutput "\p"
 
-      if opt.abbr.len > 0:
-        helpOutput fgOption, styleBright, "-", opt.abbr, ", "
-      elif appInfo.hasAbbrs:
-        # Add additional indentatition, so all names are aligned
-        helpOutput "    "
+    # Indent all command-line switches
+    helpOutput " "
 
-      if opt.name.len > 0:
-        let switch = "--" & opt.name
-        helpOutput fgOption, styleBright,
-                   switch, padding(switch, appInfo.namesWidth)
-      else:
-        helpOutput spaces(2 + appInfo.namesWidth)
+    if opt.abbr.len > 0:
+      helpOutput fgOption, styleBright, "-", opt.abbr, ", "
+    elif appInfo.hasAbbrs:
+      # Add additional indentatition, so all names are aligned
+      helpOutput "    "
+
+    if opt.name.len > 0:
+      let switch = "--" & opt.name
+      helpOutput fgOption, styleBright,
+                  switch, padding(switch, appInfo.namesWidth)
+    else:
+      helpOutput spaces(2 + appInfo.namesWidth)
 
-      if opt.desc.len > 0:
-        help.writeDesc appInfo,
-                       opt.desc.replace("%t", opt.typename),
-                       opt.defaultInHelpText
-        help.writeLongDesc appInfo, opt.longDesc
+    if opt.desc.len > 0:
+      help.writeDesc appInfo,
+                      opt.desc.replace("%t", opt.typename),
+                      opt.defaultInHelpText
+      help.writeLongDesc appInfo, opt.longDesc
 
-      helpOutput "\p"
+    helpOutput "\p"
 
+    # TODO: this is not reached: https://github.com/status-im/nim-confutils/issues/39
+    when false:
       if opt.kind == Discriminator:
         for i, subCmd in opt.subCmds:
           if not subCmd.hasOpts: continue
@@ -371,6 +367,34 @@ proc describeOptions(help: var string,
           if i == opt.defaultSubCmd: helpOutput " (default)"
           help.describeOptions subCmd, cmdInvocation, appInfo, conditionalOpts
 
+proc describeOptions(
+  help: var string,
+  cmd: CmdInfo,
+  cmdInvocation: string,
+  appInfo: HelpAppInfo,
+  optionsType = normalOpts,
+  activeCmds: openArray[CmdInfo] = @[]
+) =
+  var hasOpts = cmd.hasOpts
+  for c in activeCmds:
+    if c.hasOpts:
+      hasOpts = true
+
+  if hasOpts:
+    case optionsType
+    of normalOpts:
+      helpOutput "\pThe following options are available:\p\p"
+    of conditionalOpts:
+      helpOutput ", the following additional options are available:\p\p"
+    of defaultCmdOpts:
+      discard
+
+    if activeCmds.len > 0:
+      for c in activeCmds:
+        describeOptionsList(help, c, appInfo)
+    else:
+      describeOptionsList(help, cmd, appInfo)
+
   let subCmdDiscriminator = cmd.getSubCmdDiscriminator
   if subCmdDiscriminator != nil:
     let defaultCmdIdx = subCmdDiscriminator.defaultSubCmd
@@ -396,11 +420,13 @@ proc showHelp(help: var string,
 
   appInfo.maxNameLen = cmd.maxNameLen
   appInfo.hasAbbrs = cmd.hasAbbrs
-  appInfo.terminalWidth =
+  let termWidth =
     try:
       terminalWidth()
     except ValueError:
       int.high  # https://github.com/nim-lang/Nim/pull/21968
+  if appInfo.terminalWidth == 0:
+    appInfo.terminalWidth = termWidth
   appInfo.namesWidth = min(minNameWidth, appInfo.maxNameLen) + descPadding
 
   var cmdInvocation = appInfo.appInvocation
@@ -411,7 +437,7 @@ proc showHelp(help: var string,
   # Write out the app or script name
   helpOutput fgSection, "Usage: \p"
   help.describeInvocation cmd, cmdInvocation, appInfo
-  help.describeOptions cmd, cmdInvocation, appInfo
+  help.describeOptions cmd, cmdInvocation, appInfo, activeCmds = activeCmds
   helpOutput "\p"
 
   flushOutputAndQuit QuitSuccess
@@ -920,7 +946,8 @@ proc loadImpl[C, SecondarySources](
     secondarySources: proc (
         config: Configuration, sources: ref SecondarySources
     ) {.gcsafe, raises: [ConfigurationError].} = nil,
-    envVarsPrefix = appInvocation()
+    envVarsPrefix = appInvocation(),
+    termWidth = 0
 ): Configuration {.raises: [ConfigurationError].} =
   ## Loads a program configuration by parsing command-line arguments
   ## and a standard set of config files that can specify:
@@ -1094,7 +1121,8 @@ proc loadImpl[C, SecondarySources](
   proc lazyHelpAppInfo: HelpAppInfo =
     HelpAppInfo(
       copyrightBanner: copyrightBanner,
-      appInvocation: appInvocation())
+      appInvocation: appInvocation(),
+      terminalWidth: termWidth)
 
   template processHelpAndVersionOptions(optKey: string) =
     let key = optKey
@@ -1200,12 +1228,13 @@ template load*(
     quitOnFailure = true,
     ignoreUnknown = false,
     secondarySources: untyped = nil,
-    envVarsPrefix = appInvocation()): untyped =
+    envVarsPrefix = appInvocation(),
+    termWidth = 0): untyped =
   block:
     let secondarySourcesRef = generateSecondarySources(Configuration)
     loadImpl(Configuration, cmdLine, version,
              copyrightBanner, printUsage, quitOnFailure, ignoreUnknown,
-             secondarySourcesRef, secondarySources, envVarsPrefix)
+             secondarySourcesRef, secondarySources, envVarsPrefix, termWidth)
 
 func defaults*(Configuration: type): Configuration =
   load(Configuration, cmdLine = @[], printUsage = false, quitOnFailure = false)

tests/help/.gitignore

@@ -0,0 +1,5 @@
+/*
+!*/
+!/*.nim
+!.gitignore
+!README.md

tests/help/README.md

@@ -0,0 +1,9 @@
+## What?
+
+The way to test --help output changes is to remove all files under `snapshot`
+and run `./tests/test_help.nim` so the snapshots get generated again with
+the new content. Then you can check what changed compared to the original file.
+
+The snapshots are the output of the `*.nim --help` programs in this directory.
+
+Once your done commit the changes including the new snapshots.

tests/help/snapshots/test_nested_cmd.txt

@@ -0,0 +1,30 @@
+Usage: 
+
+test_nested_cmd [OPTIONS]... command
+
+The following options are available:
+
+ --top-arg1      topArg1 desc [=topArg1 default].
+ --lvl1-no-command-arg1  lvl1NoCommandArg1 desc [=lvl1NoCommandArg1 default].
+
+Available sub-commands:
+
+test_nested_cmd lvl1Cmd1 [OPTIONS]... command
+
+The following options are available:
+
+ --lvl1-cmd1-arg1  lvl1Cmd1Arg1 desc [=lvl1Cmd1Arg1 default].
+
+Available sub-commands:
+
+test_nested_cmd lvl1Cmd1 lvl2Cmd1 [OPTIONS]...
+
+The following options are available:
+
+ --lvl2-cmd1-arg1  lvl2Cmd1Arg1 desc [=lvl2Cmd1Arg1 default].
+
+test_nested_cmd lvl1Cmd1 lvl2Cmd2 [OPTIONS]...
+
+The following options are available:
+
+ --lvl2-cmd2-arg1  lvl2Cmd2Arg1 desc [=lvl2Cmd2Arg1 default].

tests/help/snapshots/test_nested_cmd_lvl1Cmd1.txt

@@ -0,0 +1,22 @@
+Usage: 
+
+test_nested_cmd lvl1Cmd1 [OPTIONS]... command
+
+The following options are available:
+
+ --top-arg1            topArg1 desc [=topArg1 default].
+ --lvl1-cmd1-arg1      lvl1Cmd1Arg1 desc [=lvl1Cmd1Arg1 default].
+
+Available sub-commands:
+
+test_nested_cmd lvl1Cmd1 lvl2Cmd1 [OPTIONS]...
+
+The following options are available:
+
+ --lvl2-cmd1-arg1      lvl2Cmd1Arg1 desc [=lvl2Cmd1Arg1 default].
+
+test_nested_cmd lvl1Cmd1 lvl2Cmd2 [OPTIONS]...
+
+The following options are available:
+
+ --lvl2-cmd2-arg1      lvl2Cmd2Arg1 desc [=lvl2Cmd2Arg1 default].

tests/help/snapshots/test_nested_cmd_lvl1Cmd1_lvl2Cmd2.txt

@@ -0,0 +1,9 @@
+Usage: 
+
+test_nested_cmd lvl1Cmd1 lvl2Cmd2 [OPTIONS]...
+
+The following options are available:
+
+ --top-arg1            topArg1 desc [=topArg1 default].
+ --lvl1-cmd1-arg1      lvl1Cmd1Arg1 desc [=lvl1Cmd1Arg1 default].
+ --lvl2-cmd2-arg1      lvl2Cmd2Arg1 desc [=lvl2Cmd2Arg1 default].

tests/help/test_nested_cmd.nim

@@ -0,0 +1,44 @@
+import ../../confutils
+
+type
+  Lvl1Cmd = enum
+    lvl1NoCommand
+    lvl1Cmd1
+
+  Lvl2Cmd = enum
+    lvl2Cmd1
+    lvl2Cmd2
+
+  TestConf = object
+    topArg1 {.
+      defaultValue: "topArg1 default"
+      desc: "topArg1 desc"
+      name: "top-arg1" }: string
+
+    case cmd {.
+      command
+      defaultValue: Lvl1Cmd.lvl1NoCommand }: Lvl1Cmd
+    of Lvl1Cmd.lvl1NoCommand:
+      lvl1NoCommandArg1 {.
+        defaultValue: "lvl1NoCommandArg1 default"
+        desc: "lvl1NoCommandArg1 desc"
+        name: "lvl1-no-command-arg1" }: string
+    of Lvl1Cmd.lvl1Cmd1:
+      lvl1Cmd1Arg1 {.
+        defaultValue: "lvl1Cmd1Arg1 default"
+        desc: "lvl1Cmd1Arg1 desc"
+        name: "lvl1-cmd1-arg1" }: string
+
+      case lvl2Cmd {.command.}: Lvl2Cmd
+      of Lvl2Cmd.lvl2Cmd1:
+        lvl2Cmd1Arg1 {.
+          defaultValue: "lvl2Cmd1Arg1 default"
+          desc: "lvl2Cmd1Arg1 desc"
+          name: "lvl2-cmd1-arg1" }: string
+      of Lvl2Cmd.lvl2Cmd2:
+        lvl2Cmd2Arg1 {.
+          defaultValue: "lvl2Cmd2Arg1 default"
+          desc: "lvl2Cmd2Arg1 desc"
+          name: "lvl2-cmd2-arg1" }: string
+
+let c = TestConf.load(termWidth = int.high)

tests/test_all.nim

@@ -14,7 +14,8 @@ import
   test_parsecmdarg,
   test_pragma,
   test_qualified_ident,
-  test_nested_cmd
+  test_nested_cmd,
+  test_help
 
 when defined(windows):
   import test_winreg

tests/test_help.nim

@@ -0,0 +1,64 @@
+# confutils
+# Copyright (c) 2018-2025 Status Research & Development GmbH
+# Licensed under either of
+#  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE))
+#  * MIT license ([LICENSE-MIT](LICENSE-MIT))
+# at your option.
+# This file may not be copied, modified, or distributed except according to
+# those terms.
+
+import
+  std/[os, osproc, strutils],
+  unittest2,
+  stew/byteutils,
+  ../confutils
+
+const helpPath = "tests" / "help"
+const snapshotsPath = helpPath / "snapshots"
+
+func normalizeHelp(s: string): string =
+  s.replace("\x1B[0m", "")
+    .replace("\r\n", "\n")
+    .strip(leading = false)
+
+func cmdsToName(cmds: string): string =
+  if cmds.len == 0:
+    ""
+  else:
+    "_" & cmds.replace(" ", "_")
+
+proc cmdTest(cmdName: string, cmds = "") =
+  let fname = helpPath / cmdName
+  var build = "nim c --verbosity:0 --hints:off -d:confutilsNoColors"
+  if NimMajor < 2:
+    build.add " -d:nimOldCaseObjects"
+  let buildRes = execCmdEx(build & " " & fname & ".nim")
+  if buildRes.exitCode != 0:
+    checkpoint "Build output: " & buildRes.output
+    fail()
+  else:
+    let res = execCmdEx(fname & " " & cmds & " --help")
+    let output = res.output.normalizeHelp()
+    let snapshot = snapshotsPath / cmdName & cmds.cmdsToName() & ".txt"
+    if res.exitCode != 0:
+      checkpoint "Run output: " & res.output
+      fail()
+    elif not fileExists(snapshot):
+      writeFile(snapshot, output)
+      checkpoint "Snapshot created: " & snapshot
+      fail()
+    else:
+      let expected = readFile(snapshot).normalizeHelp()
+      checkpoint "Cmd output: " & $output.toBytes()
+      checkpoint "Snapshot: " & $expected.toBytes()
+      check output == expected
+
+suite "test --help":
+  test "test test_nested_cmd":
+    cmdTest("test_nested_cmd", "")
+
+  test "test test_nested_cmd lvl1Cmd1":
+    cmdTest("test_nested_cmd", "lvl1Cmd1")
+    
+  test "test test_nested_cmd lvl1Cmd1 lvl2Cmd2":
+    cmdTest("test_nested_cmd", "lvl1Cmd1 lvl2Cmd2")