From 2e3862d056a84ab73ccf4fcf2fe74462eff9402d Mon Sep 17 00:00:00 2001 From: umarcor Date: Tue, 19 Mar 2019 23:03:51 +0100 Subject: [PATCH] update(README.md): positional and custom arguments --- README.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index a909570bb..18c077fbd 100644 --- a/README.md +++ b/README.md @@ -382,30 +382,33 @@ rootCmd.MarkFlagRequired("region") ## Positional and Custom Arguments Validation of positional arguments can be specified using the `Args` field -of `Command`. +of `Command`. The following validators are built in: -The following validators are built in: +- `NoArgs` - report an error if there are any positional args. +- `ArbitraryArgs` - accept any args. +- `MinimumNArgs(int)` - report an error if leass 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`. -- `NoArgs` - the command will report an error if there are any positional args. -- `ArbitraryArgs` - the command will accept any args. -- `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. -- `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. +If `Args` is undefined or `nil`, it defaults to `ArbitraryArgs`. -If field `ValidArgs` of type `[]string` is defined in `Command`, apart from checking the number of positional arguments according to the validators above, the command will report an error if there are any positional args that are not in the list. +Field `ValidArgs` of type `[]string` can be defined in `Command`, in order to report an error if there are any positional args that are not in the list. This validation is executed implicitly before the validator defined in `Args`. -> NOTE: `OnlyValidArgs` and `ExactValidArgs(int)` are now deprecated. Instead, use `ArbitraryArgs` and `ExactArgs(int)`. +> NOTE: `OnlyValidArgs` and `ExactValidArgs(int)` are now deprecated. `ArbitraryArgs` and `ExactArgs(int)` provide the same functionality now. -An example of setting the custom validator: +Moreover, 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 } +*/ if myapp.IsValidColor(args[0]) { return nil }