README.md
1# complete
2
3[![Build Status](https://travis-ci.org/posener/complete.svg?branch=master)](https://travis-ci.org/posener/complete)
4[![codecov](https://codecov.io/gh/posener/complete/branch/master/graph/badge.svg)](https://codecov.io/gh/posener/complete)
5[![golangci](https://golangci.com/badges/github.com/posener/complete.svg)](https://golangci.com/r/github.com/posener/complete)
6[![GoDoc](https://godoc.org/github.com/posener/complete?status.svg)](http://godoc.org/github.com/posener/complete)
7[![goreadme](https://goreadme.herokuapp.com/badge/posener/complete.svg)](https://goreadme.herokuapp.com)
8
9Package complete provides a tool for bash writing bash completion in go, and bash completion for the go command line.
10
11Writing bash completion scripts is a hard work. This package provides an easy way
12to create bash completion scripts for any command, and also an easy way to install/uninstall
13the completion of the command.
14
15#### Go Command Bash Completion
16
17In [./cmd/gocomplete](./cmd/gocomplete) there is an example for bash completion for the `go` command line.
18
19This is an example that uses the `complete` package on the `go` command - the `complete` package
20can also be used to implement any completions, see #usage.
21
22#### Install
23
241. Type in your shell:
25
26```go
27go get -u github.com/posener/complete/gocomplete
28gocomplete -install
29```
30
312. Restart your shell
32
33Uninstall by `gocomplete -uninstall`
34
35#### Features
36
37- Complete `go` command, including sub commands and all flags.
38- Complete packages names or `.go` files when necessary.
39- Complete test names after `-run` flag.
40
41#### Complete package
42
43Supported shells:
44
45- [x] bash
46- [x] zsh
47- [x] fish
48
49#### Usage
50
51Assuming you have program called `run` and you want to have bash completion
52for it, meaning, if you type `run` then space, then press the `Tab` key,
53the shell will suggest relevant complete options.
54
55In that case, we will create a program called `runcomplete`, a go program,
56with a `func main()` and so, that will make the completion of the `run`
57program. Once the `runcomplete` will be in a binary form, we could
58`runcomplete -install` and that will add to our shell all the bash completion
59options for `run`.
60
61So here it is:
62
63```go
64import "github.com/posener/complete"
65
66func main() {
67
68 // create a Command object, that represents the command we want
69 // to complete.
70 run := complete.Command{
71
72 // Sub defines a list of sub commands of the program,
73 // this is recursive, since every command is of type command also.
74 Sub: complete.Commands{
75
76 // add a build sub command
77 "build": complete.Command {
78
79 // define flags of the build sub command
80 Flags: complete.Flags{
81 // build sub command has a flag '-cpus', which
82 // expects number of cpus after it. in that case
83 // anything could complete this flag.
84 "-cpus": complete.PredictAnything,
85 },
86 },
87 },
88
89 // define flags of the 'run' main command
90 Flags: complete.Flags{
91 // a flag -o, which expects a file ending with .out after
92 // it, the tab completion will auto complete for files matching
93 // the given pattern.
94 "-o": complete.PredictFiles("*.out"),
95 },
96
97 // define global flags of the 'run' main command
98 // those will show up also when a sub command was entered in the
99 // command line
100 GlobalFlags: complete.Flags{
101
102 // a flag '-h' which does not expects anything after it
103 "-h": complete.PredictNothing,
104 },
105 }
106
107 // run the command completion, as part of the main() function.
108 // this triggers the autocompletion when needed.
109 // name must be exactly as the binary that we want to complete.
110 complete.New("run", run).Run()
111}
112```
113
114#### Self completing program
115
116In case that the program that we want to complete is written in go we
117can make it self completing.
118Here is an example: [./example/self/main.go](./example/self/main.go) .
119
120## Sub Packages
121
122* [cmd](./cmd): Package cmd used for command line options for the complete tool
123
124* [gocomplete](./gocomplete): Package main is complete tool for the go command line
125
126* [match](./match): Package match contains matchers that decide if to apply completion.
127
128
129---
130
131Created by [goreadme](https://github.com/apps/goreadme)
132