0745e55762
The completion code attempts to detect whether a flag can be specified
more than once, and therefore should provide completion even if already
set.
Currently, this code depends on conventions used in the pflag package,
which uses an "Array" or "Slice" suffix or for some types a "stringTo"
prefix.
Cobra allows custom value types to be used, which may not use the same
convention for naming, and therefore currently aren't detected to allow
multiple values.
The pflag module defines a [SliceValue] interface, which is implemented
by the Slice and Array value types it provides (unfortunately, it's not
currently implemented by the "stringTo" values).
This patch adds a reduced interface based on the [SliceValue] interface
mentioned above to allow detecting Value-types that accept multiple values.
Custom types can implement this interface to make completion work for
those values.
I deliberately used a reduced interface to keep the requirements for this
detection as low as possible, without enforcing the other methods defined
in the interface (Append, Replace) which may not apply to all custom types.
Future improvements can likely still be made, considering either implementing
the SliceValue interface for the "stringTo" values or defining a separate
"MapValue" interface for those types.
Possibly providing the reduced interface as part of the pflag module and
to export it.
[SliceValue]:
|
||
|---|---|---|
| .github | ||
| assets | ||
| doc | ||
| site/content | ||
| .gitignore | ||
| .golangci.yml | ||
| .mailmap | ||
| active_help.go | ||
| active_help_test.go | ||
| args.go | ||
| args_test.go | ||
| bash_completions.go | ||
| bash_completions_test.go | ||
| bash_completionsV2.go | ||
| bash_completionsV2_test.go | ||
| cobra.go | ||
| cobra_test.go | ||
| command.go | ||
| command_go120.go | ||
| command_go121.go | ||
| command_notwin.go | ||
| command_test.go | ||
| command_win.go | ||
| completions.go | ||
| completions_test.go | ||
| CONDUCT.md | ||
| CONTRIBUTING.md | ||
| fish_completions.go | ||
| fish_completions_test.go | ||
| flag_groups.go | ||
| flag_groups_test.go | ||
| go.mod | ||
| go.sum | ||
| LICENSE.txt | ||
| MAINTAINERS | ||
| Makefile | ||
| powershell_completions.go | ||
| powershell_completions_test.go | ||
| README.md | ||
| shell_completions.go | ||
| zsh_completions.go | ||
| zsh_completions_test.go | ||
Cobra is a library for creating powerful modern CLI applications.
Cobra is used in many Go projects such as Kubernetes, Hugo, and GitHub CLI to name a few. This list contains a more extensive list of projects using Cobra.
Overview
Cobra is a library providing a simple interface to create powerful modern CLI interfaces similar to git & go tools.
Cobra provides:
- Easy subcommand-based CLIs:
app server,app fetch, etc. - Fully POSIX-compliant flags (including short & long versions)
- Nested subcommands
- Global, local and cascading flags
- Intelligent suggestions (
app srver... did you meanapp server?) - Automatic help generation for commands and flags
- Grouping help for subcommands
- Automatic help flag recognition of
-h,--help, etc. - Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell)
- Automatically generated man pages for your application
- Command aliases so you can change things without breaking them
- The flexibility to define your own help, usage, etc.
- Optional seamless integration with viper for 12-factor apps
Concepts
Cobra is built on a structure of commands, arguments & flags.
Commands represent actions, Args are things and Flags are modifiers for those actions.
The best applications read like sentences when used, and as a result, users intuitively know how to interact with them.
The pattern to follow is
APPNAME VERB NOUN --ADJECTIVE
or
APPNAME COMMAND ARG --FLAG.
A few good real world examples may better illustrate this point.
In the following example, 'server' is a command, and 'port' is a flag:
hugo server --port=1313
In this command we are telling Git to clone the url bare.
git clone URL --bare
Commands
Command is the central point of the application. Each interaction that the application supports will be contained in a Command. A command can have children commands and optionally run an action.
In the example above, 'server' is the command.
Flags
A flag is a way to modify the behavior of a command. Cobra supports fully POSIX-compliant flags as well as the Go flag package. A Cobra command can define flags that persist through to children commands and flags that are only available to that command.
In the example above, 'port' is the flag.
Flag functionality is provided by the pflag library, a fork of the flag standard library which maintains the same interface while adding POSIX compliance.
Installing
Using Cobra is easy. First, use go get to install the latest version
of the library.
go get -u github.com/spf13/cobra@latest
Next, include Cobra in your application:
import "github.com/spf13/cobra"
Usage
cobra-cli is a command line program to generate cobra applications and command files.
It will bootstrap your application scaffolding to rapidly
develop a Cobra-based application. It is the easiest way to incorporate Cobra into your application.
It can be installed by running:
go install github.com/spf13/cobra-cli@latest
For complete details on using the Cobra-CLI generator, please read The Cobra Generator README
For complete details on using the Cobra library, please read The Cobra User Guide.
License
Cobra is released under the Apache 2.0 license. See LICENSE.txt