add subcommands to usage text

TanklesXL · Mar 14, 2024 · 75e9bab · 75e9bab
1 parent 9c51911
commit 75e9bab
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 82 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased](https://github.com/TanklesXL/glint/compare/v0.18.0...HEAD)
 
+- add subcommands to usage text
+
 ## [0.18.0](https://github.com/TanklesXL/glint/compare/v0.17.1...v0.18.0)
 
 - support for group flags at a given path

diff --git a/src/glint.gleam b/src/glint.gleam
@@ -524,12 +524,12 @@ fn execute_root(
           False ->
             snag.error(
               "unmatched named arguments: "
-              <> {
-                contents.named_args
-                |> list.drop(list.length(named))
-                |> list.map(fn(s) { "'" <> s <> "'" })
-                |> string.join(", ")
-              },
+                <> {
+                  contents.named_args
+                  |> list.drop(list.length(named))
+                  |> list.map(fn(s) { "'" <> s <> "'" })
+                  |> string.join(", ")
+                },
             )
         }
       })
@@ -557,8 +557,8 @@ fn execute_root(
     Error(#(snag, help)) ->
       Error(
         snag.pretty_print(snag)
-        <> "\nSee the following help text, available via the '--help' flag.\n\n"
-        <> help,
+          <> "\nSee the following help text, available via the '--help' flag.\n\n"
+          <> help,
       )
   }
 }
@@ -750,8 +750,8 @@ fn build_subcommands_help(
     Metadata(
       name: name,
       description: cmd.contents
-        |> option.map(fn(command) { command.description })
-        |> option.unwrap(""),
+      |> option.map(fn(command) { command.description })
+      |> option.unwrap(""),
     ),
     ..acc
   ]
@@ -814,26 +814,6 @@ fn args_count_to_usage_string(count: ArgsCount) -> String {
   }
 }
 
-fn args_to_usage_string(
-  unnamed: Option(ArgsCount),
-  named: List(String),
-) -> String {
-  let named_args =
-    named
-    |> list.map(fn(s) { "<" <> s <> ">" })
-    |> string.join(" ")
-  let unnamed_args =
-    option.map(unnamed, args_count_to_usage_string)
-    |> option.unwrap("[ ARGS ]")
-
-  case named_args, unnamed_args {
-    "", "" -> ""
-    "", _ -> unnamed_args
-    _, "" -> named_args
-    _, _ -> named_args <> " " <> unnamed_args
-  }
-}
-
 /// convert a CommandHelp to a styled usage block
 ///
 fn command_help_to_usage_string(help: CommandHelp, config: Config) -> String {
@@ -844,8 +824,21 @@ fn command_help_to_usage_string(help: CommandHelp, config: Config) -> String {
   }
 
   let flags = flags_help_to_usage_string(help.flags)
+  let subcommands =
+    list.map(help.subcommands, fn(sc) { sc.name })
+    |> list.sort(string.compare)
+    |> string.join(" | ")
+    |> string_map(string.append("( ", _))
+    |> string_map(string.append(_, " )"))
+
+  let named_args =
+    help.named_args
+    |> list.map(fn(s) { "<" <> s <> ">" })
+    |> string.join(" ")
 
-  let args = args_to_usage_string(help.unnamed_args, help.named_args)
+  let unnamed_args =
+    option.map(help.unnamed_args, args_count_to_usage_string)
+    |> option.unwrap("[ ARGS ]")
 
   case config.pretty_help {
     None -> usage_heading
@@ -854,11 +847,10 @@ fn command_help_to_usage_string(help: CommandHelp, config: Config) -> String {
   <> "\n\t"
   <> app_name
   <> string_map(help.meta.name, string.append(" ", _))
-  <> case args {
-    "" -> " "
-    _ -> " " <> args <> " "
-  }
-  <> flags
+  <> string_map(subcommands, string.append(" ", _))
+  <> string_map(named_args, string.append(" ", _))
+  <> string_map(unnamed_args, string.append(" ", _))
+  <> string_map(flags, string.append(" ", _))
 }
 
 // -- HELP - FUNCTIONS - STRINGIFIERS - FLAGS --

diff --git a/test/glint_test.gleam b/test/glint_test.gleam
@@ -99,35 +99,35 @@ pub fn help_test() {
   let global_flag = #(
     "global",
     flag.string()
-      |> flag.description("This is a global flag"),
+    |> flag.description("This is a global flag"),
   )
 
   let flag_1 = #(
     "flag1",
     flag.string()
-      |> flag.description("This is flag1"),
+    |> flag.description("This is flag1"),
   )
 
   let flag_2 = #(
     "flag2",
     flag.int()
-      |> flag.description("This is flag2"),
+    |> flag.description("This is flag2"),
   )
   let flag_3 = #(
     "flag3",
     flag.bool()
-      |> flag.description("This is flag3"),
+    |> flag.description("This is flag3"),
   )
   let flag_4 = #(
     "flag4",
     flag.float()
-      |> flag.description("This is flag4"),
+    |> flag.description("This is flag4"),
   )
 
   let flag_5 = #(
     "flag5",
     flag.float_list()
-      |> flag.description("This is flag5"),
+    |> flag.description("This is flag5"),
   )
 
   let cli =
@@ -138,43 +138,43 @@ pub fn help_test() {
     |> glint.add(
       at: [],
       do: glint.command(do: nil)
-        |> glint.named_args(["arg1", "arg2"])
-        |> glint.flag(flag_1.0, flag_1.1)
-        |> glint.description("This is the root command"),
+      |> glint.named_args(["arg1", "arg2"])
+      |> glint.flag(flag_1.0, flag_1.1)
+      |> glint.description("This is the root command"),
     )
     |> glint.add(
       at: ["cmd1"],
       do: glint.command(nil)
-        |> glint.flag(flag_2.0, flag_2.1)
-        |> glint.flag(flag_5.0, flag_5.1)
-        |> glint.description("This is cmd1"),
+      |> glint.flag(flag_2.0, flag_2.1)
+      |> glint.flag(flag_5.0, flag_5.1)
+      |> glint.description("This is cmd1"),
     )
     |> glint.add(
       at: ["cmd1", "cmd3"],
       do: glint.command(nil)
-        |> glint.flag(flag_3.0, flag_3.1)
-        |> glint.description("This is cmd3")
-        |> glint.unnamed_args(glint.MinArgs(2))
-        |> glint.named_args(["woo"]),
+      |> glint.flag(flag_3.0, flag_3.1)
+      |> glint.description("This is cmd3")
+      |> glint.unnamed_args(glint.MinArgs(2))
+      |> glint.named_args(["woo"]),
     )
     |> glint.add(
       at: ["cmd1", "cmd4"],
       do: glint.command(nil)
-        |> glint.flag(flag_4.0, flag_4.1)
-        |> glint.description("This is cmd4")
-        |> glint.unnamed_args(glint.EqArgs(0)),
+      |> glint.flag(flag_4.0, flag_4.1)
+      |> glint.description("This is cmd4")
+      |> glint.unnamed_args(glint.EqArgs(0)),
     )
     |> glint.add(
       at: ["cmd2"],
       do: glint.command(nil)
-        |> glint.named_args(["arg1", "arg2"])
-        |> glint.description("This is cmd2")
-        |> glint.unnamed_args(glint.EqArgs(0)),
+      |> glint.named_args(["arg1", "arg2"])
+      |> glint.description("This is cmd2")
+      |> glint.unnamed_args(glint.EqArgs(0)),
     )
     |> glint.add(
       at: ["cmd5", "cmd6"],
       do: glint.command(nil)
-        |> glint.description("This is cmd6"),
+      |> glint.description("This is cmd6"),
     )
 
   // execute root command
@@ -206,7 +206,7 @@ pub fn help_test() {
       "This is the root command
 
 USAGE:
-\tgleam run -m test <arg1> <arg2> [ ARGS ] [ --flag1=<STRING> --global=<STRING> ]
+\tgleam run -m test ( cmd1 | cmd2 | cmd5 ) <arg1> <arg2> [ ARGS ] [ --flag1=<STRING> --global=<STRING> ]
 
 FLAGS:
 \t--flag1=<STRING>\t\tThis is flag1
@@ -228,7 +228,7 @@ SUBCOMMANDS:
 This is cmd1
 
 USAGE:
-\tgleam run -m test cmd1 [ ARGS ] [ --flag2=<INT> --flag5=<FLOAT_LIST> --global=<STRING> ]
+\tgleam run -m test cmd1 ( cmd3 | cmd4 ) [ ARGS ] [ --flag2=<INT> --flag5=<FLOAT_LIST> --global=<STRING> ]
 
 FLAGS:
 \t--flag2=<INT>\t\tThis is flag2
@@ -298,8 +298,8 @@ pub fn global_and_group_flags_test() {
     |> glint.global_flag(
       "f",
       flag.int()
-        |> flag.default(2)
-        |> flag.description("global flag example"),
+      |> flag.default(2)
+      |> flag.description("global flag example"),
     )
     |> glint.add(
       [],
@@ -311,34 +311,34 @@ pub fn global_and_group_flags_test() {
     |> glint.add(
       ["sub"],
       glint.command(fn(ctx) {
-          flag.get_bool(ctx.flags, "f")
-          |> should.equal(Ok(True))
-        })
-        |> glint.flag(
-          "f",
-          flag.bool()
-            |> flag.default(True)
-            |> flag.description("i decided to override the global flag"),
-        ),
+        flag.get_bool(ctx.flags, "f")
+        |> should.equal(Ok(True))
+      })
+      |> glint.flag(
+        "f",
+        flag.bool()
+        |> flag.default(True)
+        |> flag.description("i decided to override the global flag"),
+      ),
     )
     |> glint.group_flag(
       ["sub"],
       "sub_group_flag",
       flag.int()
-        |> flag.default(1),
+      |> flag.default(1),
     )
     |> glint.add(
       ["sub", "sub"],
       glint.command(fn(ctx) {
-          flag.get_int(ctx.flags, "sub_group_flag")
-          |> should.equal(Ok(2))
-        })
-        |> glint.flag(
-          "f",
-          flag.bool()
-            |> flag.default(True)
-            |> flag.description("i decided to override the global flag"),
-        ),
+        flag.get_int(ctx.flags, "sub_group_flag")
+        |> should.equal(Ok(2))
+      })
+      |> glint.flag(
+        "f",
+        flag.bool()
+        |> flag.default(True)
+        |> flag.description("i decided to override the global flag"),
+      ),
     )
 
   // root command keeps the global flag as an int