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