github.com/gechr/complete@v0.0.0-20191016221035-401475e3ce1e/doc.go (about)

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