Merge pull request #105 from posener/goreadme

readme: Update according to go doc
posener · Nov 17, 2019 · a7d83cc · a7d83cc
2 parents 00c7945 + 49b2fcb
commit a7d83cc
Showing 1 changed file with 100 additions and 73 deletions.
diff --git a/README.md b/README.md
@@ -6,39 +6,50 @@
 [![GoDoc](https://godoc.org/github.com/posener/complete?status.svg)](http://godoc.org/github.com/posener/complete)
 [![goreadme](https://goreadme.herokuapp.com/badge/posener/complete.svg)](https://goreadme.herokuapp.com)
 
-Package complete provides a tool for bash writing bash completion in go, and bash completion for the go command line.
+Package complete is everything for bash completion and Go.
 
-Writing bash completion scripts is a hard work. This package provides an easy way
-to create bash completion scripts for any command, and also an easy way to install/uninstall
-the completion of the command.
+Writing bash completion scripts is a hard work, usually done in the bash scripting language.
+This package provides:
 
-#### Go Command Bash Completion
+* A library for bash completion for Go programs.
+
+* A tool for writing bash completion script in the Go language. For any Go or non Go program.
+
+* Bash completion for the `go` command line (See [./gocomplete](./gocomplete)).
 
-In [./cmd/gocomplete](./cmd/gocomplete) there is an example for bash completion for the `go` command line.
+* Library for bash-completion enabled flags (See [./compflag](./compflag)).
 
-This is an example that uses the `complete` package on the `go` command - the `complete` package
-can also be used to implement any completions, see #usage.
+* Enables an easy way to install/uninstall the completion of the command.
+
+The library and tools are extensible such that any program can add its one logic, completion types
+or methologies.
+
+#### Go Command Bash Completion
 
-#### Install
+[./gocomplete](./gocomplete) is the script for bash completion for the `go` command line. This is an example
+that uses the `complete` package on the `go` command - the `complete` package can also be used to
+implement any completions, see #usage.
+
+Install:
 
 1. Type in your shell:
 
 ```go
 go get -u github.com/posener/complete/gocomplete
-gocomplete -install
+COMP_INSTALL=1 gocomplete
 ```
 
 2. Restart your shell
 
-Uninstall by `gocomplete -uninstall`
+Uninstall by `COMP_UNINSTALL=1 gocomplete`
 
-#### Features
+Features:
 
-- Complete `go` command, including sub commands and all flags.
+- Complete `go` command, including sub commands and flags.
 - Complete packages names or `.go` files when necessary.
 - Complete test names after `-run` flag.
 
-#### Complete package
+#### Complete Package
 
 Supported shells:
 
@@ -48,82 +59,98 @@ Supported shells:
 
 #### Usage
 
-Assuming you have program called `run` and you want to have bash completion
-for it, meaning, if you type `run` then space, then press the `Tab` key,
-the shell will suggest relevant complete options.
-
-In that case, we will create a program called `runcomplete`, a go program,
-with a `func main()` and so, that will make the completion of the `run`
-program. Once the `runcomplete` will be in a binary form, we could
-`runcomplete -install` and that will add to our shell all the bash completion
-options for `run`.
-
-So here it is:
+Add bash completion capabilities to any Go program. See [./example/command](./example/command).
 
 ```go
-import "github.com/posener/complete"
+import (
+	"flag"
+	"github.com/posener/complete"
+	"github.com/posener/complete/predict"
+)
+
+var (
+	// Add variables to the program.
+	name      = flag.String("name", "", "")
+	something = flag.String("something", "", "")
+	nothing   = flag.String("nothing", "", "")
+)
 
 func main() {
-
-	// create a Command object, that represents the command we want
-	// to complete.
-	run := complete.Command{
-
-		// Sub defines a list of sub commands of the program,
-		// this is recursive, since every command is of type command also.
-		Sub: complete.Commands{
-
-			// add a build sub command
-			"build": complete.Command {
-
-				// define flags of the build sub command
-				Flags: complete.Flags{
-					// build sub command has a flag '-cpus', which
-					// expects number of cpus after it. in that case
-					// anything could complete this flag.
-					"-cpus": complete.PredictAnything,
-				},
-			},
+	// Create the complete command.
+	// Here we define completion values for each flag.
+	cmd := &complete.Command{
+		Flags: map[string]complete.Predictor{
+			"name":      predict.Set{"foo", "bar", "foo bar"},
+			"something": predict.Something,
+			"nothing":   predict.Nothing,
 		},
+	}
+	// Run the completion - provide it with the binary name.
+	cmd.Complete("my-program")
+	// Parse the flags.
+	flag.Parse()
+	// Program logic...
+}
+```
 
-		// define flags of the 'run' main command
-		Flags: complete.Flags{
-			// a flag -o, which expects a file ending with .out after
-			// it, the tab completion will auto complete for files matching
-			// the given pattern.
-			"-o": complete.PredictFiles("*.out"),
-		},
-
-		// define global flags of the 'run' main command
-		// those will show up also when a sub command was entered in the
-		// command line
-		GlobalFlags: complete.Flags{
-
-			// a flag '-h' which does not expects anything after it
-			"-h": complete.PredictNothing,
-		},
+This package also enables to complete flags defined by the standard library `flag` package.
+To use this feature, simply call `complete.CommandLine` before `flag.Parse`. (See [./example/stdlib](./example/stdlib)).
+
+```diff
+  	import (
+		"flag"
+ +		"github.com/posener/complete"
+	)
+	var (
+		// Define flags here...
+		foo = flag.Bool("foo", false, "")
+	)
+
+	func main() {
+		// Call command line completion before parsing the flags - provide it with the binary name.
+ +		complete.CommandLine("my-program")
+		flag.Parse()
 	}
+```
 
-	// run the command completion, as part of the main() function.
-	// this triggers the autocompletion when needed.
-	// name must be exactly as the binary that we want to complete.
-	complete.New("run", run).Run()
-}
+If flag value completion is desired, it can be done by providing the standard library `flag.Var`
+function a `flag.Value` that also implements the `complete.Predictor` interface. For standard
+flag with values, it is possible to use the `github.com/posener/complete/compflag` package.
+(See [./example/compflag](./example/compflag)).
+
+```diff
+  	import (
+		"flag"
+ +		"github.com/posener/complete"
+ +		"github.com/posener/complete/compflag"
+	)
+	var (
+		// Define flags here...
+ -		foo = flag.Bool("foo", false, "")
+ +		foo = compflag.Bool("foo", false, "")
+	)
+
+	func main() {
+		// Call command line completion before parsing the flags.
+ +		complete.CommandLine("my-program")
+		flag.Parse()
+	}
 ```
 
-#### Self completing program
+Instead of calling both `complete.CommandLine` and `flag.Parse`, one can call just `compflag.Parse`
+which does them both.
+
+#### Testing
 
-In case that the program that we want to complete is written in go we
-can make it self completing.
-Here is an example: [./example/self/main.go](./example/self/main.go) .
+For command line bash completion testing use the `complete.Test` function.
 
 ## Sub Packages
 
-* [cmd](./cmd): Package cmd used for command line options for the complete tool
+* [compflag](./compflag): Package compflag provides a handful of standard library-compatible flags with bash complition capabilities.
 
 * [gocomplete](./gocomplete): Package main is complete tool for the go command line
 
-* [match](./match): Package match contains matchers that decide if to apply completion.
+* [predict](./predict): Package predict provides helper functions for completion predictors.
 
 
 ---