interesting
/
complete
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update readme according to go doc

This commit is contained in:
goreadme 2019-11-17 23:10:11 +00:00
parent 00c7945465
commit 49b2fcbf4b
1 changed files with 101 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
README.md
View File

@ -6,39 +6,50 @@
[![GoDoc](https://godoc.org/github.com/posener/complete?status.svg)](http://godoc.org/github.com/posener/complete) [![GoDoc](https://godoc.org/github.com/posener/complete?status.svg)](http://godoc.org/github.com/posener/complete)
[![goreadme](https://goreadme.herokuapp.com/badge/posener/complete.svg)](https://goreadme.herokuapp.com) [![goreadme](https://goreadme.herokuapp.com/badge/posener/complete.svg)](https://goreadme.herokuapp.com)
Package complete provides a tool for bash writing bash completion in go, and bash completion for the go command line. Package complete is everything for bash completion and Go.
Writing bash completion scripts is a hard work. This package provides an easy way Writing bash completion scripts is a hard work, usually done in the bash scripting language.
to create bash completion scripts for any command, and also an easy way to install/uninstall This package provides:
the completion of the command.
* A library for bash completion for Go programs.
* A tool for writing bash completion script in the Go language. For any Go or non Go program.
* Bash completion for the `go` command line (See [./gocomplete](./gocomplete)).
* Library for bash-completion enabled flags (See [./compflag](./compflag)).
* Enables an easy way to install/uninstall the completion of the command.
The library and tools are extensible such that any program can add its one logic, completion types
or methologies.
#### Go Command Bash Completion #### Go Command Bash Completion
In [./cmd/gocomplete](./cmd/gocomplete) there is an example for bash completion for the `go` command line. [./gocomplete](./gocomplete) is the script for bash completion for the `go` command line. This is an example
that uses the `complete` package on the `go` command - the `complete` package can also be used to
implement any completions, see #usage.
This is an example that uses the `complete` package on the `go` command - the `complete` package Install:
can also be used to implement any completions, see #usage.
#### Install
1. Type in your shell: 1. Type in your shell:
```go ```go
go get -u github.com/posener/complete/gocomplete go get -u github.com/posener/complete/gocomplete
gocomplete -install COMP_INSTALL=1 gocomplete
``` ```
2. Restart your shell 2. Restart your shell
Uninstall by `gocomplete -uninstall` Uninstall by `COMP_UNINSTALL=1 gocomplete`
#### Features Features:
- Complete `go` command, including sub commands and all flags. - Complete `go` command, including sub commands and flags.
- Complete packages names or `.go` files when necessary. - Complete packages names or `.go` files when necessary.
- Complete test names after `-run` flag. - Complete test names after `-run` flag.
#### Complete package #### Complete Package
Supported shells: Supported shells:
@ -48,82 +59,98 @@ Supported shells:
#### Usage #### Usage
Assuming you have program called `run` and you want to have bash completion Add bash completion capabilities to any Go program. See [./example/command](./example/command).
for it, meaning, if you type `run` then space, then press the `Tab` key,
the shell will suggest relevant complete options.
In that case, we will create a program called `runcomplete`, a go program,
with a `func main()` and so, that will make the completion of the `run`
program. Once the `runcomplete` will be in a binary form, we could
`runcomplete -install` and that will add to our shell all the bash completion
options for `run`.
So here it is:
```go ```go
import "github.com/posener/complete" import (
"flag"
"github.com/posener/complete"
"github.com/posener/complete/predict"
)
var (
// Add variables to the program.
name = flag.String("name", "", "")
something = flag.String("something", "", "")
nothing = flag.String("nothing", "", "")
)
func main() { func main() {
// Create the complete command.
// create a Command object, that represents the command we want // Here we define completion values for each flag.
// to complete. cmd := &complete.Command{
run := complete.Command{ Flags: map[string]complete.Predictor{
"name": predict.Set{"foo", "bar", "foo bar"},
// Sub defines a list of sub commands of the program, "something": predict.Something,
// this is recursive, since every command is of type command also. "nothing": predict.Nothing,
Sub: complete.Commands{
// add a build sub command
"build": complete.Command {
// define flags of the build sub command
Flags: complete.Flags{
// build sub command has a flag '-cpus', which
// expects number of cpus after it. in that case
// anything could complete this flag.
"-cpus": complete.PredictAnything,
},
},
},
// define flags of the 'run' main command
Flags: complete.Flags{
// a flag -o, which expects a file ending with .out after
// it, the tab completion will auto complete for files matching
// the given pattern.
"-o": complete.PredictFiles("*.out"),
},
// define global flags of the 'run' main command
// those will show up also when a sub command was entered in the
// command line
GlobalFlags: complete.Flags{
// a flag '-h' which does not expects anything after it
"-h": complete.PredictNothing,
}, },
} }
// Run the completion - provide it with the binary name.
// run the command completion, as part of the main() function. cmd.Complete("my-program")
// this triggers the autocompletion when needed. // Parse the flags.
// name must be exactly as the binary that we want to complete. flag.Parse()
complete.New("run", run).Run() // Program logic...
} }
``` ```
#### Self completing program This package also enables to complete flags defined by the standard library `flag` package.
To use this feature, simply call `complete.CommandLine` before `flag.Parse`. (See [./example/stdlib](./example/stdlib)).
In case that the program that we want to complete is written in go we ```diff
can make it self completing. import (
Here is an example: [./example/self/main.go](./example/self/main.go) . "flag"
+ "github.com/posener/complete"
)
var (
// Define flags here...
foo = flag.Bool("foo", false, "")
)
func main() {
// Call command line completion before parsing the flags - provide it with the binary name.
+ complete.CommandLine("my-program")
flag.Parse()
}
```
If flag value completion is desired, it can be done by providing the standard library `flag.Var`
function a `flag.Value` that also implements the `complete.Predictor` interface. For standard
flag with values, it is possible to use the `github.com/posener/complete/compflag` package.
(See [./example/compflag](./example/compflag)).
```diff
import (
"flag"
+ "github.com/posener/complete"
+ "github.com/posener/complete/compflag"
)
var (
// Define flags here...
- foo = flag.Bool("foo", false, "")
+ foo = compflag.Bool("foo", false, "")
)
func main() {
// Call command line completion before parsing the flags.
+ complete.CommandLine("my-program")
flag.Parse()
}
```
Instead of calling both `complete.CommandLine` and `flag.Parse`, one can call just `compflag.Parse`
which does them both.
#### Testing
For command line bash completion testing use the `complete.Test` function.
## Sub Packages ## Sub Packages
* [cmd](./cmd): Package cmd used for command line options for the complete tool * [compflag](./compflag): Package compflag provides a handful of standard library-compatible flags with bash complition capabilities.
* [gocomplete](./gocomplete): Package main is complete tool for the go command line * [gocomplete](./gocomplete): Package main is complete tool for the go command line
* [match](./match): Package match contains matchers that decide if to apply completion. * [predict](./predict): Package predict provides helper functions for completion predictors.
--- ---