--- a/vendor/github.com/spf13/cobra/user_guide.md Thu Sep 22 16:37:07 2022 +0200
+++ b/vendor/github.com/spf13/cobra/user_guide.md Sat Feb 04 12:58:35 2023 +0100
@@ -302,15 +302,15 @@
### Flag Groups
-If you have different flags that must be provided together (e.g. if they provide the `--username` flag they MUST provide the `--password` flag as well) then
+If you have different flags that must be provided together (e.g. if they provide the `--username` flag they MUST provide the `--password` flag as well) then
Cobra can enforce that requirement:
```go
rootCmd.Flags().StringVarP(&u, "username", "u", "", "Username (required if password is set)")
rootCmd.Flags().StringVarP(&pw, "password", "p", "", "Password (required if username is set)")
rootCmd.MarkFlagsRequiredTogether("username", "password")
-```
+```
-You can also prevent different flags from being provided together if they represent mutually
+You can also prevent different flags from being provided together if they represent mutually
exclusive options such as specifying an output format as either `--json` or `--yaml` but never both:
```go
rootCmd.Flags().BoolVar(&u, "json", false, "Output in JSON")
@@ -327,29 +327,47 @@
## Positional and Custom Arguments
Validation of positional arguments can be specified using the `Args` field of `Command`.
-If `Args` is undefined or `nil`, it defaults to `ArbitraryArgs`.
-
The following validators are built in:
-- `NoArgs` - the command will report an error if there are any positional args.
-- `ArbitraryArgs` - the command will accept any args.
-- `OnlyValidArgs` - the command will report an error if there are any positional args that are not in the `ValidArgs` field of `Command`.
-- `MinimumNArgs(int)` - the command will report an error if there are not at least N positional args.
-- `MaximumNArgs(int)` - the command will report an error if there are more than N positional args.
-- `ExactArgs(int)` - the command will report an error if there are not exactly N positional args.
-- `ExactValidArgs(int)` - the command will report an error if there are not exactly N positional args OR if there are any positional args that are not in the `ValidArgs` field of `Command`
-- `RangeArgs(min, max)` - the command will report an error if the number of args is not between the minimum and maximum number of expected args.
-- `MatchAll(pargs ...PositionalArgs)` - enables combining existing checks with arbitrary other checks (e.g. you want to check the ExactArgs length along with other qualities).
+- Number of arguments:
+ - `NoArgs` - report an error if there are any positional args.
+ - `ArbitraryArgs` - accept any number of args.
+ - `MinimumNArgs(int)` - report an error if less than N positional args are provided.
+ - `MaximumNArgs(int)` - report an error if more than N positional args are provided.
+ - `ExactArgs(int)` - report an error if there are not exactly N positional args.
+ - `RangeArgs(min, max)` - report an error if the number of args is not between `min` and `max`.
+- Content of the arguments:
+ - `OnlyValidArgs` - report an error if there are any positional args not specified in the `ValidArgs` field of `Command`, which can optionally be set to a list of valid values for positional args.
+
+If `Args` is undefined or `nil`, it defaults to `ArbitraryArgs`.
-An example of setting the custom validator:
+Moreover, `MatchAll(pargs ...PositionalArgs)` enables combining existing checks with arbitrary other checks.
+For instance, if you want to report an error if there are not exactly N positional args OR if there are any positional
+args that are not in the `ValidArgs` field of `Command`, you can call `MatchAll` on `ExactArgs` and `OnlyValidArgs`, as
+shown below:
+
+```go
+var cmd = &cobra.Command{
+ Short: "hello",
+ Args: MatchAll(ExactArgs(2), OnlyValidArgs),
+ Run: func(cmd *cobra.Command, args []string) {
+ fmt.Println("Hello, World!")
+ },
+}
+```
+
+It is possible to set any custom validator that satisfies `func(cmd *cobra.Command, args []string) error`.
+For example:
```go
var cmd = &cobra.Command{
Short: "hello",
Args: func(cmd *cobra.Command, args []string) error {
- if len(args) < 1 {
- return errors.New("requires a color argument")
+ // Optionally run one of the validators provided by cobra
+ if err := cobra.MinimumNArgs(1)(cmd, args); err != nil {
+ return err
}
+ // Run the custom validation logic
if myapp.IsValidColor(args[0]) {
return nil
}
@@ -444,37 +462,46 @@
The following output is automatically generated by Cobra. Nothing beyond the
command and flag definitions are needed.
- $ cobra help
+ $ cobra-cli help
Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.
Usage:
- cobra [command]
+ cobra-cli [command]
Available Commands:
add Add a command to a Cobra Application
+ completion Generate the autocompletion script for the specified shell
help Help about any command
init Initialize a Cobra Application
Flags:
-a, --author string author name for copyright attribution (default "YOUR NAME")
--config string config file (default is $HOME/.cobra.yaml)
- -h, --help help for cobra
+ -h, --help help for cobra-cli
-l, --license string name of license for the project
- --viper use Viper for configuration (default true)
+ --viper use Viper for configuration
- Use "cobra [command] --help" for more information about a command.
+ Use "cobra-cli [command] --help" for more information about a command.
Help is just a command like any other. There is no special logic or behavior
around it. In fact, you can provide your own if you want.
+### Grouping commands in help
+
+Cobra supports grouping of available commands in the help output. To group commands, each group must be explicitly
+defined using `AddGroup()` on the parent command. Then a subcommand can be added to a group using the `GroupID` element
+of that subcommand. The groups will appear in the help output in the same order as they are defined using different
+calls to `AddGroup()`. If you use the generated `help` or `completion` commands, you can set their group ids using
+`SetHelpCommandGroupId()` and `SetCompletionCommandGroupId()` on the root command, respectively.
+
### Defining your own help
You can provide your own Help command or your own template for the default command to use
-with following functions:
+with the following functions:
```go
cmd.SetHelpCommand(cmd *Command)
@@ -493,22 +520,23 @@
You may recognize this from the help above. That's because the default help
embeds the usage as part of its output.
- $ cobra --invalid
+ $ cobra-cli --invalid
Error: unknown flag: --invalid
Usage:
- cobra [command]
+ cobra-cli [command]
Available Commands:
add Add a command to a Cobra Application
+ completion Generate the autocompletion script for the specified shell
help Help about any command
init Initialize a Cobra Application
Flags:
-a, --author string author name for copyright attribution (default "YOUR NAME")
--config string config file (default is $HOME/.cobra.yaml)
- -h, --help help for cobra
+ -h, --help help for cobra-cli
-l, --license string name of license for the project
- --viper use Viper for configuration (default true)
+ --viper use Viper for configuration
Use "cobra [command] --help" for more information about a command.
@@ -627,7 +655,7 @@
Run 'hugo --help' for usage.
```
-Suggestions are automatic based on every subcommand registered and use an implementation of [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance). Every registered command that matches a minimum distance of 2 (ignoring case) will be displayed as a suggestion.
+Suggestions are automatically generated based on existing subcommands and use an implementation of [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance). Every registered command that matches a minimum distance of 2 (ignoring case) will be displayed as a suggestion.
If you need to disable suggestions or tweak the string distance in your command, use:
@@ -641,7 +669,8 @@
command.SuggestionsMinimumDistance = 1
```
-You can also explicitly set names for which a given command will be suggested using the `SuggestFor` attribute. This allows suggestions for strings that are not close in terms of string distance, but makes sense in your set of commands and for some which you don't want aliases. Example:
+You can also explicitly set names for which a given command will be suggested using the `SuggestFor` attribute. This allows suggestions for strings that are not close in terms of string distance, but make sense in your set of commands but for which
+you don't want aliases. Example:
```
$ kubectl remove