expose ActionCommands

Co-authored-by: maxlandon <[email protected]>

Author: rsteube

defaultActions.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/rsteube/carapace/internal/common"
 	"github.com/rsteube/carapace/internal/config"
+	"github.com/rsteube/carapace/internal/env"
 	"github.com/rsteube/carapace/internal/export"
 	"github.com/rsteube/carapace/internal/man"
 	"github.com/rsteube/carapace/pkg/match"
@@ -480,3 +481,36 @@ func ActionPositional(cmd *cobra.Command) Action {
 		return a.Invoke(c).ToA()
 	})
 }
+
+// ActionCommands completes (sub)commands of given command.
+// `Context.Args` is used to traverse the command tree further down. Use `Action.Shift` to avoid this.
+//
+//	carapace.Gen(helpCmd).PositionalAnyCompletion(
+//		carapace.ActionCommands(rootCmd),
+//	)
+func ActionCommands(cmd *cobra.Command) Action {
+	return ActionCallback(func(c Context) Action {
+		if len(c.Args) > 0 {
+			for _, subCommand := range cmd.Commands() {
+				for _, name := range append(subCommand.Aliases, subCommand.Name()) {
+					if name == c.Args[0] { // cmd.Find is too lenient
+						return ActionCommands(subCommand).Shift(1)
+					}
+				}
+			}
+			return ActionMessage("unknown subcommand %#v for %#v", c.Args[0], cmd.Name())
+		}
+
+		batch := Batch()
+		for _, subcommand := range cmd.Commands() {
+			if (!subcommand.Hidden || env.Hidden()) && subcommand.Deprecated == "" {
+				group := common.Group{Cmd: subcommand}
+				batch = append(batch, ActionStyledValuesDescribed(subcommand.Name(), subcommand.Short, group.Style()).Tag(group.Tag()))
+				for _, alias := range subcommand.Aliases {
+					batch = append(batch, ActionStyledValuesDescribed(alias, subcommand.Short, group.Style()).Tag(group.Tag()))
+				}
+			}
+		}
+		return batch.ToA()
+	})
+}

docs/src/SUMMARY.md

@@ -55,6 +55,7 @@
     - [ToMultiPartsA](./carapace/invokedAction/toMultiPartsA.md)
   - [DefaultActions](./carapace/defaultActions.md)
     - [ActionCallback](./carapace/defaultActions/actionCallback.md)
+    - [ActionCommands](./carapace/defaultActions/actionCommands.md)
     - [ActionDirectories](./carapace/defaultActions/actionDirectories.md)
     - [ActionExecCommand](./carapace/defaultActions/actionExecCommand.md)
     - [ActionExecCommandE](./carapace/defaultActions/actionExecCommandE.md)

docs/src/carapace/defaultActions/actionCommands.cast

@@ -0,0 +1,17 @@
+# ActionCommands
+
+[`ActionCommands`] completes (sub)commands of given command.
+
+> `Context.Args` is used to traverse the command tree further down.
+> Use [Shift](../action/shift.md) to avoid this.
+
+
+```go
+carapace.Gen(helpCmd).PositionalAnyCompletion(
+	carapace.ActionCommands(cmd),
+)
+```
+
+![](./actionCommands.cast)
+
+[`ActionCommands`]:https://pkg.go.dev/github.com/rsteube/carapace#ActionCommands

docs/src/carapace/defaultActions/actionCommands.md

@@ -21,6 +21,7 @@ func init() {
 	rootCmd.AddCommand(actionCmd)
 
 	actionCmd.Flags().String("callback", "", "ActionCallback()")
+	actionCmd.Flags().String("commands", "", "ActionCommands()")
 	actionCmd.Flags().String("directories", "", "ActionDirectories()")
 	actionCmd.Flags().String("execcommand", "", "ActionExecCommand()")
 	actionCmd.Flags().String("execcommandE", "", "ActionExecCommand()")
@@ -48,6 +49,7 @@ func init() {
 			}
 			return carapace.ActionMessage("values flag is not set")
 		}),
+		"commands":    carapace.ActionCommands(rootCmd).Split(),
 		"directories": carapace.ActionDirectories(),
 		"execcommand": carapace.ActionExecCommand("git", "remote")(func(output []byte) carapace.Action {
 			lines := strings.Split(string(output), "\n")

example/cmd/action.go

@@ -24,6 +24,44 @@ func TestAction(t *testing.T) {
 			Expect(carapace.ActionMessage("values flag is not set").
 				Usage("ActionCallback()"))
 
+		s.Run("action", "--commands", "s").
+			Expect(carapace.ActionValuesDescribed(
+				"special", "",
+				"subcommand", "subcommand example",
+			).Suffix(" ").
+				NoSpace().
+				Tag("other commands").
+				Usage("ActionCommands()"))
+
+		s.Run("action", "--commands", "subcommand ").
+			Expect(carapace.Batch(
+				carapace.ActionValuesDescribed(
+					"a1", "subcommand with alias",
+					"a2", "subcommand with alias",
+					"alias", "subcommand with alias",
+				).Tag("other commands"),
+				carapace.ActionValuesDescribed(
+					"group", "subcommand with group",
+				).Style(style.Blue).Tag("group commands"),
+			).ToA().
+				Prefix("subcommand ").
+				Suffix(" ").
+				NoSpace().
+				Usage("ActionCommands()"))
+
+		s.Run("action", "--commands", "subcommand unknown ").
+			Expect(carapace.ActionMessage(`unknown subcommand "unknown" for "subcommand"`).NoSpace().
+				Usage("ActionCommands()"))
+
+		s.Run("action", "--commands", "subcommand hidden ").
+			Expect(carapace.ActionValuesDescribed(
+				"visible", "visible subcommand of a hidden command",
+			).Prefix("subcommand hidden ").
+				Suffix(" ").
+				NoSpace().
+				Tag("commands").
+				Usage("ActionCommands()"))
+
 		s.Run("action", "--values", "first", "--callback", "").
 			Expect(carapace.ActionMessage("values flag is set to: 'first'").
 				Usage("ActionCallback()"))

example/cmd/action_test.go

@@ -0,0 +1,22 @@
+package cmd
+
+import (
+	"github.com/rsteube/carapace"
+	"github.com/spf13/cobra"
+)
+
+var subcommandCmd = &cobra.Command{
+	Use:   "subcommand",
+	Short: "subcommand example",
+	Run:   func(cmd *cobra.Command, args []string) {},
+}
+
+func init() {
+	carapace.Gen(subcommandCmd).Standalone()
+
+	subcommandCmd.AddGroup(
+		&cobra.Group{ID: "group", Title: ""},
+	)
+
+	rootCmd.AddCommand(subcommandCmd)
+}

example/cmd/subcommand.go

@@ -0,0 +1,19 @@
+package cmd
+
+import (
+	"github.com/rsteube/carapace"
+	"github.com/spf13/cobra"
+)
+
+var subcommand_aliasCmd = &cobra.Command{
+	Use:     "alias",
+	Short:   "subcommand with alias",
+	Aliases: []string{"a1", "a2"},
+	Run:     func(cmd *cobra.Command, args []string) {},
+}
+
+func init() {
+	carapace.Gen(subcommand_aliasCmd).Standalone()
+
+	subcommandCmd.AddCommand(subcommand_aliasCmd)
+}

example/cmd/subcommand_alias.go

@@ -0,0 +1,19 @@
+package cmd
+
+import (
+	"github.com/rsteube/carapace"
+	"github.com/spf13/cobra"
+)
+
+var subcommand_groupCmd = &cobra.Command{
+	Use:     "group",
+	Short:   "subcommand with group",
+	GroupID: "group",
+	Run:     func(cmd *cobra.Command, args []string) {},
+}
+
+func init() {
+	carapace.Gen(subcommand_groupCmd).Standalone()
+
+	subcommandCmd.AddCommand(subcommand_groupCmd)
+}

example/cmd/subcommand_group.go

@@ -0,0 +1,19 @@
+package cmd
+
+import (
+	"github.com/rsteube/carapace"
+	"github.com/spf13/cobra"
+)
+
+var subcommand_hiddenCmd = &cobra.Command{
+	Use:    "hidden",
+	Short:  "hidden subcommand",
+	Hidden: true,
+	Run:    func(cmd *cobra.Command, args []string) {},
+}
+
+func init() {
+	carapace.Gen(subcommand_hiddenCmd).Standalone()
+
+	subcommandCmd.AddCommand(subcommand_hiddenCmd)
+}