refactor docs, add examples (bitfield#94)

refactor docs, add examples

Author: bitfield

CONTRIBUTING.md

@@ -4,7 +4,6 @@ So you'd like to contribute to the `script` library? Excellent! Thank you very m
 	- [Look for existing issues](#look-for-existing-issues)
 	- [Open a new issue before making a PR](#open-a-new-issue-before-making-a-pr)
 	- [Write a use case](#write-a-use-case)
-	- [Ideas](#ideas)
 - [Coding standards](#coding-standards)
 	- [Tests](#tests)
 		- [Use the standard library](#use-the-standard-library)
@@ -54,16 +53,6 @@ A concrete use case also provides a helpful example program that can be included
 
 The final reason is that it's tempting to over-elaborate a design and add all sorts of bells and whistles that nobody actually wants. Simple APIs are best. If you think of an enhancement, but it's not needed for your use case, leave it out. Things can always be enhanced later if necessary.
 
-## Ideas
-
-These are some ideas I've been thinking about. Some of them have existing issues and PRs with active discussion, so check those first.
-
-* `Get()` makes a web request, like `curl`, and pipes the result
-* `Net()` makes a network connection to a specified address and port, and reads the connection until it's closed
-* `ListFiles()` takes a filesystem path or glob, and pipes the list of matching files
-* `Find()` pipes a list of files matching various criteria (name, modified time, and so on)
-* `Processes()` pipes the list of running processes, like `ps`.
-
 # Coding standards
 
 A library is easier to use, and easier for contributors to work on, if it has a consistent, unified style, approach, and layout. Here are a few hints on how to make a `script` PR that will be accepted right away.
@@ -157,9 +146,7 @@ This is the _whole_ user manual for your code. It will be included in the autoge
 
 ## Update the README
 
-Any change to the `script` API should also be accompanied by an update to the README. If you add a new method, add it in the appropriate place (sources, filters, or sinks), in its correct order alphabetically, and with a suitable (brief) example of its use.
-
-The README has a table of contents that is automatically generated and updated (when I work on it) by the VS Code [Markdown All In One](github.com/yzhang-gh/vscode-markdown) extension. However, you don't need to use this to update the table of contents yourself. The format should be fairly self-explanatory.
+Any change to the `script` API should also be accompanied by an update to the README. If you add a new method, add it in the appropriate place (sources, filters, or sinks), in its correct order alphabetically, and with a suitable (brief) description.
 
 # Writing pipe operations
 

README.md

@@ -0,0 +1,341 @@
+package script_test
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/bitfield/script"
+)
+
+func ExampleArgs() {
+	script.Args().Stdout()
+	// prints command-line arguments
+}
+
+func ExampleEcho() {
+	script.Echo("Hello, world!").Stdout()
+	// Output:
+	// Hello, world!
+}
+
+func ExampleExec_ok() {
+	script.Exec("echo Hello, world!").Stdout()
+	// Output:
+	// Hello, world!
+}
+
+func ExampleExec_exitstatus() {
+	p := script.Exec("echo")
+	fmt.Println(p.ExitStatus())
+	// Output:
+	// 0
+}
+
+func ExampleFile() {
+	script.File("testdata/hello.txt").Stdout()
+	// Output:
+	// hello world
+}
+
+func ExampleFindFiles() {
+	script.FindFiles("testdata/multiple_files_with_subdirectory").Stdout()
+	// Output:
+	// testdata/multiple_files_with_subdirectory/1.txt
+	// testdata/multiple_files_with_subdirectory/2.txt
+	// testdata/multiple_files_with_subdirectory/3.tar.zip
+	// testdata/multiple_files_with_subdirectory/dir/.hidden
+	// testdata/multiple_files_with_subdirectory/dir/1.txt
+	// testdata/multiple_files_with_subdirectory/dir/2.txt
+}
+
+func ExampleIfExists_true() {
+	script.IfExists("./testdata/hello.txt").Echo("found it").Stdout()
+	// Output:
+	// found it
+}
+
+func ExampleIfExists_false() {
+	script.IfExists("doesntexist").Echo("found it").Stdout()
+	// Output:
+	//
+}
+
+func ExampleListFiles() {
+	script.ListFiles("testdata/multiple_files_with_subdirectory").Stdout()
+	// Output:
+	// testdata/multiple_files_with_subdirectory/1.txt
+	// testdata/multiple_files_with_subdirectory/2.txt
+	// testdata/multiple_files_with_subdirectory/3.tar.zip
+	// testdata/multiple_files_with_subdirectory/dir
+}
+
+func ExamplePipe_Basename() {
+	input := []string{
+		"",
+		"/",
+		"/root",
+		"/tmp/example.php",
+		"/var/tmp/",
+		"./src/filters",
+		"C:/Program Files",
+	}
+	script.Slice(input).Basename().Stdout()
+	// Output:
+	// .
+	// /
+	// root
+	// example.php
+	// tmp
+	// filters
+	// Program Files
+}
+
+func ExamplePipe_Bytes() {
+	data, err := script.Echo("hello").Bytes()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(data)
+	// Output:
+	// [104 101 108 108 111]
+}
+
+func ExamplePipe_Column() {
+	input := []string{
+		"PID   TT  STAT      TIME COMMAND",
+		"  1   ??  Ss   873:17.62 /sbin/launchd",
+		" 50   ??  Ss    13:18.13 /usr/libexec/UserEventAgent (System)",
+		" 51   ??  Ss    22:56.75 /usr/sbin/syslogd",
+	}
+	script.Slice(input).Column(1).Stdout()
+	// Output:
+	// PID
+	// 1
+	// 50
+	// 51
+}
+
+func ExamplePipe_Concat() {
+	input := []string{
+		"testdata/test.txt",
+		"testdata/doesntexist.txt",
+		"testdata/hello.txt",
+	}
+	script.Slice(input).Concat().Stdout()
+	// Output:
+	// This is the first line in the file.
+	// Hello, world.
+	// This is another line in the file.
+	// hello world
+}
+
+func ExamplePipe_CountLines() {
+	n, err := script.Echo("a\nb\nc\n").CountLines()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(n)
+	// Output:
+	// 3
+}
+
+func ExamplePipe_Dirname() {
+	input := []string{
+		"",
+		"/",
+		"/root",
+		"/tmp/example.php",
+		"/var/tmp/",
+		"./src/filters",
+		"C:/Program Files",
+	}
+	script.Slice(input).Dirname().Stdout()
+	// Output:
+	// .
+	// /
+	// /
+	// /tmp
+	// /var
+	// ./src
+	// C:
+}
+
+func ExamplePipe_EachLine() {
+	script.File("testdata/test.txt").EachLine(func(line string, out *strings.Builder) {
+		out.WriteString("> " + line + "\n")
+	}).Stdout()
+	// Output:
+	// > This is the first line in the file.
+	// > Hello, world.
+	// > This is another line in the file.
+}
+
+func ExamplePipe_Echo() {
+	script.NewPipe().Echo("Hello, world!").Stdout()
+	// Output:
+	// Hello, world!
+}
+
+func ExamplePipe_Exec() {
+	script.Echo("Hello, world!").Exec("tr a-z A-Z").Stdout()
+	// Output:
+	// HELLO, WORLD!
+}
+
+func ExamplePipe_ExecForEach() {
+	script.Echo("a\nb\nc\n").ExecForEach("echo {{.}}").Stdout()
+	// Output:
+	// a
+	// b
+	// c
+}
+
+func ExamplePipe_ExitStatus() {
+	p := script.Exec("echo")
+	fmt.Println(p.ExitStatus())
+	// Output:
+	// 0
+}
+
+func ExamplePipe_First() {
+	script.Echo("a\nb\nc\n").First(2).Stdout()
+	// Output:
+	// a
+	// b
+}
+
+func ExamplePipe_Freq() {
+	script.File("testdata/freq.input.txt").Freq().Stdout()
+	// Output:
+	// 10 apple
+	//  4 banana
+	//  4 orange
+	//  1 kumquat
+}
+
+func ExamplePipe_Join() {
+	script.Echo("hello\nworld\n").Join().Stdout()
+	// Output:
+	// hello world
+}
+
+func ExamplePipe_Last() {
+	script.Echo("a\nb\nc\n").Last(2).Stdout()
+	// Output:
+	// b
+	// c
+}
+
+func ExamplePipe_Match() {
+	script.Echo("a\nb\nc\n").Match("b").Stdout()
+	// Output:
+	// b
+}
+
+func ExamplePipe_MatchRegexp() {
+	re := regexp.MustCompile("w.*d")
+	script.Echo("hello\nworld\n").MatchRegexp(re).Stdout()
+	// Output:
+	// world
+}
+
+func ExamplePipe_Read() {
+	buf := make([]byte, 12)
+	n, err := script.Echo("hello world\n").Read(buf)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(n)
+	// Output:
+	// 12
+}
+
+func ExamplePipe_Reject() {
+	script.Echo("a\nb\nc\n").Reject("b").Stdout()
+	// Output:
+	// a
+	// c
+}
+
+func ExamplePipe_RejectRegexp() {
+	re := regexp.MustCompile("w.*d")
+	script.Echo("hello\nworld\n").RejectRegexp(re).Stdout()
+	// Output:
+	// hello
+}
+
+func ExamplePipe_Replace() {
+	script.Echo("a\nb\nc\n").Replace("b", "replacement").Stdout()
+	// Output:
+	// a
+	// replacement
+	// c
+}
+
+func ExamplePipe_ReplaceRegexp() {
+	re := regexp.MustCompile("w.*d")
+	script.Echo("hello\nworld\n").ReplaceRegexp(re, "replacement").Stdout()
+	// Output:
+	// hello
+	// replacement
+}
+
+func ExamplePipe_SHA256Sum() {
+	sum, err := script.Echo("hello world").SHA256Sum()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(sum)
+	// Output:
+	// b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+}
+
+func ExamplePipe_SHA256Sums() {
+	script.Echo("testdata/test.txt").SHA256Sums().Stdout()
+	// Output:
+	// a562c9c95e2ff3403e7ffcd8508c6b54d47d5f251387758d3e63dbaaa8296341
+}
+
+func ExamplePipe_Slice() {
+	s, err := script.Echo("a\nb\nc\n").Slice()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(s)
+	// Output:
+	// [a b c]
+}
+
+func ExamplePipe_Stdout() {
+	n, err := script.Echo("a\nb\nc\n").Stdout()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(n)
+	// Output:
+	// a
+	// b
+	// c
+	// 6
+}
+
+func ExamplePipe_String() {
+	s, err := script.Echo("hello\nworld").String()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(s)
+	// Output:
+	// hello
+	// world
+}
+
+func ExampleSlice() {
+	input := []string{"1", "2", "3"}
+	script.Slice(input).Stdout()
+	// Output:
+	// 1
+	// 2
+	// 3
+}