Merge pull request #5 from hairyhenderson/update-docs

Updating docs

.circleci/config.yml

@@ -63,9 +63,9 @@ jobs:
       - run:
           name: make integration
           command: |
-            trap "go-junit-report < /tmp/test-results/go-test.out > /tmp/test-results/report.xml" EXIT
-            make test | tee /tmp/test-results/go-test.out
-            echo $? > test.exit
+            trap "go-junit-report < /tmp/test-results/go-integration.out > /tmp/test-results/integration-report.xml" EXIT
+            make integration | tee /tmp/test-results/go-integration.out
+            echo $? > integration.exit
       - store_test_results:
           path: /tmp/test-results
       - store_artifacts:

Makefile

@@ -112,7 +112,7 @@ test:
 
 integration: ./bin/$(PKG)
 	$(GO) test -v -tags=integration \
-		./tests/integration -check.v
+		./internal/tests/integration -check.v
 
 integration.iid: Dockerfile.integration $(PREFIX)/bin/$(PKG_NAME)_linux-amd64$(call extension,$(GOOS))
 	docker build -f $< --iidfile $@ .

README.md

@@ -1,5 +1,8 @@
 # go-which
 
+[![Build Status][circleci-image]][circleci-url]
+[![hairyhenderson/go-which on DockerHub][dockerhub-image]][dockerhub-url]
+
 A cross-platform Go implementation of the `which(1)` command, usable both as a CLI and library.
 
 ```console
@@ -10,3 +13,76 @@ Usage of which:
 ```
 
 Unlike the UNIX `which(1)` command, even if multiple programs are given as input, only the first one found will be returned.
+
+## CLI Usage
+
+Chances are you don't really need this, since most UNIX-like OSes come with the more established (and significantly smaller) C implementation of `which(1)`, either as a standalone binary, or as a shell builtin.
+
+_But_ if there's some reason this may be useful to you, you can use this just like the normal `which(1)`:
+
+```console
+$ which zsh
+/usr/local/bin/zsh
+$ which -a zsh
+/usr/local/bin/zsh
+/bin/zsh
+```
+
+```console
+$ which zsh bash sh
+/usr/local/bin/zsh
+$ which -a zsh bash sh
+/usr/local/bin/zsh
+/bin/zsh
+/bin/bash
+/bin/sh
+```
+
+```console
+$ if (which -s zsh bash); then
+> echo 'I have zsh and bash installed';
+> fi
+I have zsh and bash installed
+$ if (which -s zsh bash ash); then echo 'yup'
+> else
+> echo "I'm missing one of them...";
+> fi
+I'm missing one of them...
+```
+
+## Go package usage
+
+If you're writing a program in the Go language, it can be useful to not have to shell out to `which(1)` to locate a binary.
+
+The simplest usage is:
+
+```go
+package main
+
+import (
+  "fmt"
+  "github.com/hairyhenderson/go-which"
+)
+
+func main() {
+  zshPath := which.Which("zsh")
+
+  fmt.Printf("zsh found at %s", zshPath)
+}
+```
+
+See the [godocs][] for more information.
+
+## License
+
+[The MIT License](http://opensource.org/licenses/MIT)
+
+Copyright (c) 2018-2019 Dave Henderson
+
+[godocs]: https://godoc.org/github.com/hairyhenderson/go-which
+
+
+[circleci-image]: https://circleci.com/gh/hairyhenderson/go-which/tree/master.svg?style=shield
+[circleci-url]: https://circleci.com/gh/hairyhenderson/go-which/tree/master
+[dockerhub-image]: https://img.shields.io/badge/docker-ready-blue.svg
+[dockerhub-url]: https://hub.docker.com/r/hairyhenderson/go-which

cmd/which/main.go

@@ -1,7 +1,6 @@
-/*
-CLI for the which command
-*/
-
+// CLI for the which command.
+//
+// See https://github.com/hairyhenderson/go-which for details.
 package main
 
 import (

which.go

@@ -1,3 +1,8 @@
+// Package which - locates executable files in the current path. A cross-platform
+// implementation of the `which(1)` command.
+//
+// This allows finding programs by searching the current `PATH` environment
+// variable without needing to shell out to the operating system's `which` command.
 package which
 
 import (

which_test.go

@@ -3,6 +3,7 @@
 package which
 
 import (
+	"fmt"
 	"os"
 	"testing"
 
@@ -90,3 +91,83 @@ func TestFound(t *testing.T) {
 	assert.False(t, found(fs, "foo", "bar", "baz"))
 	assert.True(t, found(fs, "foo", "bar", "qux"))
 }
+
+// nolint: gochecknoinits
+func init() {
+	exampleBins := map[string][]string{
+		"sh":   {"/bin/sh"},
+		"zsh":  {"/usr/local/bin/zsh", "/bin/zsh"},
+		"bash": {"/bin/bash"},
+	}
+	for k, paths := range exampleBins {
+		if !Found(k) {
+			for _, p := range paths {
+				f, err := os.OpenFile(p, os.O_CREATE|os.O_RDWR, 0755)
+				if err != nil {
+					panic(err)
+				}
+				_, err = f.WriteString("#!/bin/sh\necho hello world\n")
+				if err != nil {
+					panic(err)
+				}
+			}
+		}
+	}
+}
+
+func ExampleWhich() {
+	path := Which("sh")
+	fmt.Printf("Found sh at: %s", path)
+
+	// Output: Found sh at: /bin/sh
+}
+
+// When given multiple arguments, `Which` will return the path for the first found
+func ExampleWhich_multiples() {
+	path := Which("bogus", "sh")
+	fmt.Printf("First found was: %s", path)
+
+	// Output: First found was: /bin/sh
+}
+
+func ExampleAll() {
+	path := All("zsh")
+	fmt.Printf("%v", path)
+
+	// Output: [/usr/local/bin/zsh /bin/zsh]
+}
+
+// When given multiple arguments, `All` will return all paths, sorted by argument order
+func ExampleAll_multiples() {
+	path := All("zsh", "bash")
+	fmt.Printf("%v", path)
+
+	// Output: [/usr/local/bin/zsh /bin/zsh /bin/bash]
+}
+
+func ExampleFound() {
+	if Found("zsh") {
+		fmt.Println("got it!")
+	}
+
+	if !Found("bogon") {
+		fmt.Println("phew, no bogons")
+	}
+
+	// Output: got it!
+	// phew, no bogons
+}
+
+// When given multiple arguments, `Found` will return all paths, sorted by argument order
+func ExampleFound_multiples() {
+	if Found("zsh", "bash") {
+		fmt.Println("a decent collection of shells")
+	}
+
+	if !Found("zsh", "bash", "ash") {
+		fmt.Println("just missing the ashes...")
+	}
+
+	// Output: a decent collection of shells
+	// just missing the ashes...
+}