Merge pull request #289 from rsteube/explicit-root

explicit root cmd

README.md

@@ -25,7 +25,7 @@ Command-line completion generator for [cobra] with support for:
 
 ## Usage
 
-Calling `carapace.Gen` on any command is sufficient to enable completion script generation using the [hidden command](https://rsteube.github.io/carapace/carapace/gen/hiddenSubcommand.html).
+Calling `carapace.Gen(rootCmd).Root()` on the root command is sufficient to enable completion script generation using the [hidden command](https://rsteube.github.io/carapace/carapace/gen/hiddenSubcommand.html).
 
 ```go
 import (

carapace.go

@@ -32,12 +32,17 @@ type Carapace struct {
 
 // Gen initialized Carapace for given command
 func Gen(cmd *cobra.Command) *Carapace {
-	addCompletionCommand(cmd)
 	return &Carapace{
 		cmd: cmd,
 	}
 }
 
+// Root marks the command as root and adds the hidden completion command (`_carapace`)
+func (c Carapace) Root() {
+	// there is no PreExecC hook in cobra so this needs to be done explicitly
+	addCompletionCommand(c.cmd)
+}
+
 // PositionalCompletion defines completion for positional arguments using a list of Actions
 func (c Carapace) PositionalCompletion(action ...Action) {
 	storage.get(c.cmd).positional = action
@@ -62,11 +67,12 @@ func (c Carapace) FlagCompletion(actions ActionMap) {
 // Standalone prevents cobra defaults interfering with standalone mode (e.g. implicit help command)
 func (c Carapace) Standalone() {
 	// TODO probably needs to be done for each subcommand
-	if c.cmd.Root().Flag("help") != nil {
-		c.cmd.Root().Flags().Bool("help", false, "skip")
-		c.cmd.Root().Flag("help").Hidden = true
+	// TODO still needed?
+	if c.cmd.Flag("help") != nil {
+		c.cmd.Flags().Bool("help", false, "skip")
+		c.cmd.Flag("help").Hidden = true
 	}
-	c.cmd.Root().SetHelpCommand(&cobra.Command{Hidden: true})
+	c.cmd.SetHelpCommand(&cobra.Command{Hidden: true})
 }
 
 // Snippet creates completion script for given shell
@@ -113,12 +119,12 @@ func lookupFlag(cmd *cobra.Command, arg string) (flag *pflag.Flag) {
 }
 
 func addCompletionCommand(cmd *cobra.Command) {
-	for _, c := range cmd.Root().Commands() {
+	for _, c := range cmd.Commands() {
 		if c.Name() == "_carapace" {
 			return
 		}
 	}
-	cmd.Root().AddCommand(&cobra.Command{
+	cmd.AddCommand(&cobra.Command{
 		Use:    "_carapace",
 		Hidden: true,
 		Run: func(cmd *cobra.Command, args []string) {

docs/src/carapace/gen.md

@@ -1,17 +1,15 @@
 # Gen
 
-Calling [`carapace.Gen`](https://pkg.go.dev/github.com/rsteube/carapace#Gen) on any command is sufficient to enable completion script generation using the [hidden subcommand](./gen/hiddenSubcommand.md).
+Calling [`Root()`](https://pkg.go.dev/github.com/rsteube/carapace#Carapace.Root) on the root command is sufficient to enable completion script generation using the [hidden subcommand](./gen/hiddenSubcommand.md).
 
 ```go
 import (
     "github.com/rsteube/carapace"
 )
 
-carapace.Gen(myCmd)
+carapace.Gen(myCmd).Root()
 ```
 
-> Invocations to `carapace.Gen` must be **after** the command was added to the parent command so that the [uids](./gen/uid.md) are correct.
-
 Additionally invoke [`carapace.Test`](https://pkg.go.dev/github.com/rsteube/carapace#Test) in a [test](https://golang.org/doc/tutorial/add-a-test) to verify configuration during build time.
 ```go
 func TestCarapace(t *testing.T) {

docs/src/carapace/gen/hiddenSubcommand.md

@@ -1,6 +1,6 @@
 # Hidden Subcommand
 
-When [`carapace.Gen`](https://pkg.go.dev/github.com/rsteube/carapace#Gen) is invoked a hidden command (`_carapace`) is added to the root command unless it already exists. This handles completion script generation and [callbacks](../action/actionCallback.md).
+When [`Root()`](https://pkg.go.dev/github.com/rsteube/carapace#Carapace.Root) is invoked a hidden command (`_carapace`) is added. This handles completion script generation and [callbacks](../action/actionCallback.md).
 
 
 ## Completion

example/cmd/root.go

@@ -25,4 +25,6 @@ func init() {
 	carapace.Gen(rootCmd).FlagCompletion(carapace.ActionMap{
 		"persistentFlag": carapace.ActionValues("p1", "p2", "p3"),
 	})
+
+	carapace.Gen(rootCmd).Root()
 }