vendor/github.com/posener/complete/readme.md

   1 # complete
   2
   3 A tool for bash writing bash completion in go, and bash completion for the go command line.
   4
   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)
   7 [![golangci](https://golangci.com/badges/github.com/posener/complete.svg)](https://golangci.com/r/github.com/posener/complete)
   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
  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
  46 - [x] fish
  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)