github.com/divan/complete@v0.0.0-20170515130636-337e95201af7/readme.md (about)

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