diff --git a/docs/v3/examples/completions/customizations.md b/docs/v3/examples/completions/customizations.md new file mode 100644 index 0000000000..06cbd67b84 --- /dev/null +++ b/docs/v3/examples/completions/customizations.md @@ -0,0 +1,142 @@ +--- +tags: + - v3 +search: + boost: 2 +--- + +If default completion isnt sufficient additional customizations are available + +- custom auto-completion +- customizing completion command + +#### Custom auto-completion + +```go +package main + +import ( + "fmt" + "log" + "os" + "context" + + "github.com/urfave/cli/v3" +) + +func main() { + tasks := []string{"cook", "clean", "laundry", "eat", "sleep", "code"} + + cmd := &cli.Command{ + EnableShellCompletion: true, + Commands: []*cli.Command{ + { + Name: "complete", + Aliases: []string{"c"}, + Usage: "complete a task on the list", + Action: func(ctx context.Context, cmd *cli.Command) error { + fmt.Println("completed task: ", cmd.Args().First()) + return nil + }, + ShellComplete: func(ctx context.Context, cmd *cli.Command) { + // This will complete if no args are passed + if cmd.NArg() > 0 { + return + } + for _, t := range tasks { + fmt.Println(t) + } + }, + }, + }, + } + + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } +} +``` +![](../../images/custom-bash-autocomplete.gif) + +#### Customize a completion command + +By default, a completion command is hidden, meaning the command isn't included in the help message. +You can customize it by setting root Command's `ConfigureShellCompletionCommand`. + +```go +package main + +import ( + "context" + "fmt" + "log" + "os" + + "github.com/urfave/cli/v3" +) + +func main() { + cmd := &cli.Command{ + Name: "greet", + // EnableShellCompletion is unnecessary + ConfigureShellCompletionCommand: func(cmd *cli.Command) { // cmd is a completion command + cmd.Hidden = false // Make a completion command public + cmd.Usage = "..." // Customize Usage + cmd.Description = "..." // Customize Description + }, + Commands: []*cli.Command{ + { + Name: "hello", + Usage: "Say hello", + Action: func(ctx context.Context, cmd *cli.Command) error { + fmt.Println("Hello") + return nil + }, + }, + }, + } + + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } +} +``` + +#### Customization + +The default shell completion flag (`--generate-shell-completion`) is defined as +`cli.EnableShellCompletion`, and may be redefined if desired, e.g.: + + +```go +package main + +import ( + "log" + "os" + "context" + + "github.com/urfave/cli/v3" +) + +func main() { + cmd := &cli.Command{ + EnableShellCompletion: true, + Commands: []*cli.Command{ + { + Name: "wat", + }, + }, + } + + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } +} +``` diff --git a/docs/v3/examples/completions/shell-completions.md b/docs/v3/examples/completions/shell-completions.md index 29b55daab3..b355a6320f 100644 --- a/docs/v3/examples/completions/shell-completions.md +++ b/docs/v3/examples/completions/shell-completions.md @@ -9,17 +9,19 @@ The urfave/cli v3 library supports programmable completion for apps utilizing it that the completion is generated dynamically at runtime by invokiong the app itself with a special hidden flag. The urfave/cli searches for this flag and activates a different flow for command paths than regular flow The following shells are supported + - bash - zsh - fish - powershell Enabling auto complete requires 2 things + - Setting the `EnableShellCompletion` field on root `Command` object to `true`. - Sourcing the completion script for that particular shell. - The completion script for a particular shell can be retrieved by running the "completion" subcommand - on the app after the `EnableShellCompletion` field on root `Command` object has been set to `true`. +The completion script for a particular shell can be retrieved by running the "completion" subcommand +on the app after the `EnableShellCompletion` field on root `Command` object has been set to `true`. Consider the following program @@ -182,137 +184,6 @@ func main() { ``` ![](../../images/default-bash-autocomplete.gif) -#### Custom auto-completion - -```go -package main - -import ( - "fmt" - "log" - "os" - "context" - - "github.com/urfave/cli/v3" -) - -func main() { - tasks := []string{"cook", "clean", "laundry", "eat", "sleep", "code"} - - cmd := &cli.Command{ - EnableShellCompletion: true, - Commands: []*cli.Command{ - { - Name: "complete", - Aliases: []string{"c"}, - Usage: "complete a task on the list", - Action: func(ctx context.Context, cmd *cli.Command) error { - fmt.Println("completed task: ", cmd.Args().First()) - return nil - }, - ShellComplete: func(ctx context.Context, cmd *cli.Command) { - // This will complete if no args are passed - if cmd.NArg() > 0 { - return - } - for _, t := range tasks { - fmt.Println(t) - } - }, - }, - }, - } - - if err := cmd.Run(context.Background(), os.Args); err != nil { - log.Fatal(err) - } -} -``` -![](../../images/custom-bash-autocomplete.gif) - -#### Customize a completion command - -By default, a completion command is hidden, meaning the command isn't included in the help message. -You can customize it by setting root Command's `ConfigureShellCompletionCommand`. - -```go -package main - -import ( - "context" - "fmt" - "log" - "os" - - "github.com/urfave/cli/v3" -) - -func main() { - cmd := &cli.Command{ - Name: "greet", - // EnableShellCompletion is unnecessary - ConfigureShellCompletionCommand: func(cmd *cli.Command) { // cmd is a completion command - cmd.Hidden = false // Make a completion command public - cmd.Usage = "..." // Customize Usage - cmd.Description = "..." // Customize Description - }, - Commands: []*cli.Command{ - { - Name: "hello", - Usage: "Say hello", - Action: func(ctx context.Context, cmd *cli.Command) error { - fmt.Println("Hello") - return nil - }, - }, - }, - } - - if err := cmd.Run(context.Background(), os.Args); err != nil { - log.Fatal(err) - } -} -``` - -#### Customization - -The default shell completion flag (`--generate-shell-completion`) is defined as -`cli.EnableShellCompletion`, and may be redefined if desired, e.g.: - - -```go -package main - -import ( - "log" - "os" - "context" - - "github.com/urfave/cli/v3" -) - -func main() { - cmd := &cli.Command{ - EnableShellCompletion: true, - Commands: []*cli.Command{ - { - Name: "wat", - }, - }, - } - - if err := cmd.Run(context.Background(), os.Args); err != nil { - log.Fatal(err) - } -} -``` - #### ZSH Support Adding the following lines to diff --git a/docs/v3/examples/flags/basics.md b/docs/v3/examples/flags/basics.md index b587ed6835..172687c568 100644 --- a/docs/v3/examples/flags/basics.md +++ b/docs/v3/examples/flags/basics.md @@ -134,6 +134,7 @@ Note that most flag can be invoked multiple times but only the last value entere will be provided to the user(with some exceptions. See flags-advanced.md) The following basic flags are supported + - `IntFlag` - `Int8Flag` - `Int16Flag` diff --git a/mkdocs.yml b/mkdocs.yml index 34b4e68471..97bc4ad589 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,6 +35,7 @@ nav: - Categories: v3/examples/subcommands/categories.md - Completions: - Shell Completions: v3/examples/completions/shell-completions.md + - Customizations: v3/examples/completions/customizations.md - Help Text: - Generated Help Text: v3/examples/help/generated-help-text.md - Suggestions: v3/examples/help/suggestions.md