Command-Line Programs

package main

import (
	"flag"
	"fmt"
	"os"
	"time"
)

func main() {
	var (
		title   = flag.String("title", "", "match books whose title contains `text`")
		limit   = flag.Int("limit", 10, "maximum number of results")
		asJSON  = flag.Bool("json", false, "print results as JSON")
		timeout = flag.Duration("timeout", 5*time.Second, "give up after this long")
	)
	var verbose bool
	flag.BoolVar(&verbose, "v", false, "verbose output")

	flag.Parse()

	fmt.Printf("title=%q limit=%d json=%t timeout=%v verbose=%t\n", *title, *limit, *asJSON, *timeout, verbose)
	fmt.Printf("NFlag=%d NArg=%d Args=%q\n", flag.NFlag(), flag.NArg(), flag.Args())
	if flag.NArg() > 0 {
		fmt.Fprintln(os.Stdout, "first positional:", flag.Arg(0))
	}
}

$ ./flagbasics -title go -limit 3
title="go" limit=3 json=false timeout=5s verbose=false
NFlag=2 NArg=0 Args=[]
$ ./flagbasics --limit=3 -json -v rest -v
title="" limit=3 json=true timeout=5s verbose=true
NFlag=3 NArg=2 Args=["rest" "-v"]
first positional: rest
$ ./flagbasics -json=false -timeout 250ms -- -title x
title="" limit=10 json=false timeout=250ms verbose=false
NFlag=2 NArg=2 Args=["-title" "x"]
first positional: -title
$ ./flagbasics -json false x
title="" limit=10 json=true timeout=5s verbose=false
NFlag=1 NArg=2 Args=["false" "x"]
first positional: false

$ ./flagbasics -limit abc
invalid value "abc" for flag -limit: parse error
Usage of ./flagbasics:
  -json
    	print results as JSON
  -limit int
    	maximum number of results (default 10)
  -timeout duration
    	give up after this long (default 5s)
  -title text
    	match books whose title contains text
  -v	verbose output
[exit status 2]
$ ./flagbasics -timeout
flag needs an argument: -timeout
Usage of ./flagbasics:
  -json
    	print results as JSON
  -limit int
    	maximum number of results (default 10)
  -timeout duration
    	give up after this long (default 5s)
  -title text
    	match books whose title contains text
  -v	verbose output
[exit status 2]
$ ./flagbasics -nope 2>&1 | head -3
flag provided but not defined: -nope
Usage of ./flagbasics:
  -json
$ ./flagbasics -h; echo status $?
Usage of ./flagbasics:
  -json
    	print results as JSON
  -limit int
    	maximum number of results (default 10)
  -timeout duration
    	give up after this long (default 5s)
  -title text
    	match books whose title contains text
  -v	verbose output
status 0

$ ./flagbasics -h 2>/dev/null | wc -c
       0

package main

import (
	"errors"
	"flag"
	"fmt"
	"log/slog"
	"os"
	"strconv"
	"strings"
)

// authors is a repeatable flag: -author A -author B. It implements flag.Value.
type authors []string

func (a *authors) String() string { return strings.Join(*a, ",") }

func (a *authors) Set(s string) error {
	if strings.TrimSpace(s) == "" {
		return errors.New("author name must not be empty")
	}
	*a = append(*a, s)
	return nil
}

func main() {
	fs := flag.NewFlagSet("shelf search", flag.ContinueOnError)
	fs.SetOutput(os.Stdout) // usage and parse errors go to stdout so the demo is easy to capture

	var by authors
	fs.Var(&by, "author", "restrict to `name` (repeatable)")

	verbosity := 0
	fs.BoolFunc("v", "increase verbosity (repeatable)", func(string) error {
		verbosity++
		return nil
	})

	var year int
	fs.Func("year", "publication `year` between 1450 and 2100", func(s string) error {
		n, err := strconv.Atoi(s)
		if err != nil {
			return errors.New("not a number")
		}
		if n < 1450 || n > 2100 {
			return fmt.Errorf("%d is out of range", n)
		}
		year = n
		return nil
	})

	level := slog.LevelInfo
	fs.TextVar(&level, "log-level", slog.LevelInfo, "log `level`: debug, info, warn or error")

	if err := fs.Parse(os.Args[1:]); err != nil {
		if errors.Is(err, flag.ErrHelp) {
			return
		}
		fmt.Println("parse failed:", err)
		os.Exit(2)
	}

	fmt.Printf("authors=%q verbosity=%d year=%d level=%v\n", by, verbosity, year, level)

	fmt.Print("set explicitly:")
	fs.Visit(func(f *flag.Flag) { fmt.Print(" ", f.Name) })
	fmt.Println()

	f := fs.Lookup("log-level")
	fmt.Printf("log-level: default %q, current %q\n", f.DefValue, f.Value)
}

$ ./flagtypes -h
Usage of shelf search:
  -author name
    	restrict to name (repeatable)
  -log-level level
    	log level: debug, info, warn or error (default INFO)
  -v	increase verbosity (repeatable)
  -year year
    	publication year between 1450 and 2100
$ ./flagtypes -author Knuth -author Pike -v -v -v -year 1978 -log-level=debug
authors=["Knuth" "Pike"] verbosity=3 year=1978 level=DEBUG
set explicitly: author log-level v year
log-level: default "INFO", current "DEBUG"
$ ./flagtypes -year 1200 | head -1
invalid value "1200" for flag -year: 1200 is out of range
$ ./flagtypes -log-level loud | head -1
invalid value "loud" for flag -log-level: slog: level string "loud": unknown name

package main

import (
	"flag"
	"fmt"
	"os"
	"path/filepath"
)

func main() {
	name := filepath.Base(os.Args[0])
	member := flag.String("member", "", "member `id` (required)")
	days := flag.Int("days", 14, "loan length in `days`")

	// flag.Usage is a variable: replace it to control the help text. It is
	// called for -h/-help and for every parse error.
	flag.Usage = func() {
		fmt.Fprintf(flag.CommandLine.Output(), "Usage: %s [flags] ISBN...\n\nLend books to a member.\n\nFlags:\n", name)
		flag.PrintDefaults()
		fmt.Fprintf(flag.CommandLine.Output(), "\nExample:\n  %s -member ana 978-0-13-419044-0\n", name)
	}
	flag.Parse() // the default error handling for the command line is ExitOnError

	// Flag.Parse cannot express "required": check it yourself, and exit with
	// the same status the flag package uses for a bad command line.
	if *member == "" || flag.NArg() == 0 {
		flag.Usage()
		os.Exit(2)
	}

	// Visit walks only the flags that were set on the command line, so it can
	// tell "-days 14" from the default of 14.
	explicit := map[string]bool{}
	flag.Visit(func(f *flag.Flag) { explicit[f.Name] = true })
	fmt.Printf("lending %q to %s for %d days (days set explicitly: %t)\n", flag.Args(), *member, *days, explicit["days"])
}

$ ./usage -h
Usage: usage [flags] ISBN...

Lend books to a member.

Flags:
  -days days
    	loan length in days (default 14)
  -member id
    	member id (required)

Example:
  usage -member ana 978-0-13-419044-0
$ ./usage
Usage: usage [flags] ISBN...

Lend books to a member.

Flags:
  -days days
    	loan length in days (default 14)
  -member id
    	member id (required)

Example:
  usage -member ana 978-0-13-419044-0
[exit status 2]
$ ./usage -member ana -days 14 978-0-13-419044-0 978-0-13-468599-1
lending ["978-0-13-419044-0" "978-0-13-468599-1"] to ana for 14 days (days set explicitly: true)
$ ./usage -member=ana 978-0-13-419044-0
lending ["978-0-13-419044-0"] to ana for 14 days (days set explicitly: false)

package main

import (
	"flag"
	"fmt"
)

func main() {
	limit := flag.Int("limit", 10, "maximum number of results")
	flag.Parse()
	for i := 0; i < limit; i++ {
		fmt.Println("result", i)
	}
}

$ go build .
# example.com/broken
./main.go:11:18: invalid operation: i < limit (mismatched types int and *int)

package main

import (
	"bufio"
	"errors"
	"fmt"
	"os"
)

func main() {
	// Is standard input a terminal, a pipe or a file?
	if fi, err := os.Stdin.Stat(); err == nil {
		switch {
		case fi.Mode()&os.ModeCharDevice != 0:
			fmt.Println("stdin: a character device (a terminal, or /dev/null)")
		case fi.Mode()&os.ModeNamedPipe != 0:
			fmt.Println("stdin: a pipe")
		case fi.Mode().IsRegular():
			fmt.Println("stdin: a redirected file")
		}
	}

	sc := bufio.NewScanner(os.Stdin)
	if len(os.Args) > 1 && os.Args[1] == "big" {
		// The default limit is 64 KiB per line (bufio.MaxScanTokenSize).
		sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
	}

	n, longest := 0, 0
	for sc.Scan() {
		n++
		longest = max(longest, len(sc.Text()))
	}
	if err := sc.Err(); err != nil {
		fmt.Fprintln(os.Stderr, "read error:", err)
		fmt.Printf("too long: %t, lines read before the error: %d\n", errors.Is(err, bufio.ErrTooLong), n)
		os.Exit(1)
	}
	fmt.Printf("lines=%d longest=%d\n", n, longest)
}

$ printf 'go\nrust\nc\n' | ./stdin
stdin: a pipe
lines=3 longest=4
$ ./stdin < cmd/stdin/main.go
stdin: a redirected file
lines=40 longest=100
$ python3 -c 'print("x"*70000)' | ./stdin
stdin: a pipe
read error: bufio.Scanner: token too long
too long: true, lines read before the error: 0
[exit status 1]
$ python3 -c 'print("x"*70000)' | ./stdin big
stdin: a pipe
lines=1 longest=70000
$ ./stdin < /dev/null
stdin: a character device (a terminal, or /dev/null)
lines=0 longest=0

package main

import (
	"bufio"
	"errors"
	"fmt"
	"io"
	"os"
	"strings"
)

// confirm asks a yes/no question on stderr (stdout stays clean for data) and
// reads the answer from in. End of input counts as "no".
func confirm(in *bufio.Reader, prompt string) (bool, error) {
	fmt.Fprintf(os.Stderr, "%s [y/N] ", prompt)
	line, err := in.ReadString('\n')
	if err != nil && !errors.Is(err, io.EOF) {
		return false, err
	}
	answer := strings.ToLower(strings.TrimSpace(line))
	return answer == "y" || answer == "yes", nil
}

func main() {
	ok, err := confirm(bufio.NewReader(os.Stdin), "Return all 3 books on loan to ana?")
	if err != nil {
		fmt.Fprintln(os.Stderr, "shelf:", err)
		os.Exit(1)
	}
	if !ok {
		fmt.Fprintln(os.Stderr, "aborted")
		os.Exit(1)
	}
	fmt.Println("returned 3 books")
}

$ echo y | ./confirm
Return all 3 books on loan to ana? [y/N] returned 3 books
[exit status 0]
$ echo no | ./confirm
Return all 3 books on loan to ana? [y/N] aborted
[exit status 1]
$ printf '' | ./confirm
Return all 3 books on loan to ana? [y/N] aborted
[exit status 1]

package main

import (
	"bufio"
	"fmt"
	"os"
	"os/signal"
	"syscall"
)

func main() {
	if len(os.Args) > 1 && os.Args[1] == "handle-sigpipe" {
		// Once SIGPIPE is registered with Notify, a write to a closed pipe on
		// stdout or stderr returns EPIPE instead of killing the process.
		signal.Notify(make(chan os.Signal, 1), syscall.SIGPIPE)
	}
	os.Exit(run())
}

func run() int {
	out := bufio.NewWriter(os.Stdout)
	for i := 1; i <= 200000; i++ {
		if _, err := fmt.Fprintf(out, "978-0-13-%06d-0 title %d\n", i, i); err != nil {
			fmt.Fprintln(os.Stderr, "shelf: write:", err)
			return 1
		}
	}
	// Flush is where buffered write errors surface: always check it.
	if err := out.Flush(); err != nil {
		fmt.Fprintln(os.Stderr, "shelf: flush:", err)
		return 1
	}
	return 0
}

$ ./pipes | head -2
978-0-13-000001-0 title 1
978-0-13-000002-0 title 2
$ ./pipes handle-sigpipe | head -2
978-0-13-000001-0 title 1
978-0-13-000002-0 title 2
shelf: write: write /dev/stdout: broken pipe

package main

import (
	"fmt"
	"os"
	"os/signal"
)

func main() {
	sigs := make(chan os.Signal)
	signal.Notify(sigs, os.Interrupt)
	fmt.Println("waiting for Ctrl-C")
	<-sigs
}

$ go vet .
main.go:11:2: misuse of unbuffered os.Signal channel as argument to signal.Notify

package main

import (
	"context"
	"fmt"
	"os"
	"os/signal"
	"syscall"
	"time"
)

func main() {
	self, err := os.FindProcess(os.Getpid())
	if err != nil {
		panic(err)
	}

	// 1. Notify: a buffered channel receives the signals. The buffer must hold
	// at least one value because the package never blocks when it sends.
	sigs := make(chan os.Signal, 1)
	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
	self.Signal(syscall.SIGTERM)
	select {
	case s := <-sigs:
		fmt.Println("Notify received:", s)
	case <-time.After(5 * time.Second):
		fmt.Println("no signal")
	}
	signal.Stop(sigs) // unregister; SIGTERM would now terminate the process again

	// 2. NotifyContext: the context is cancelled by the first signal, and
	// context.Cause says which one.
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()
	self.Signal(os.Interrupt)
	select {
	case <-ctx.Done():
		fmt.Println("NotifyContext: Err =", ctx.Err())
		fmt.Println("NotifyContext: Cause =", context.Cause(ctx))
	case <-time.After(5 * time.Second):
		fmt.Println("no signal")
	}

	// 3. After stop, signals behave as before Notify. A second Ctrl-C now kills
	// the process with the default action instead of being swallowed.
	stop()
	fmt.Println("stopped; sending SIGINT with the default action restored")
	self.Signal(os.Interrupt)
	time.Sleep(5 * time.Second)
	fmt.Println("not reached")
}

$ ./signals
Notify received: terminated
NotifyContext: Err = context canceled
NotifyContext: Cause = interrupt signal received
stopped; sending SIGINT with the default action restored
[exit status 130]

package main

import (
	"context"
	"errors"
	"flag"
	"fmt"
	"os"
	"os/signal"
	"syscall"
	"time"
)

func main() {
	cleanup := flag.Duration("cleanup", 0, "simulated time needed to flush before exiting")
	flag.Parse()
	os.Exit(run(*cleanup))
}

func run(cleanup time.Duration) int {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	// After the first signal, give the default behaviour back: a second
	// Ctrl-C then terminates the process even if cleanup hangs.
	go func() {
		<-ctx.Done()
		stop()
		fmt.Fprintln(os.Stderr, "shelf: interrupted, finishing the current record (press Ctrl-C again to force quit)")
	}()

	fmt.Println("importing")
	done, err := importRecords(ctx, 20)
	fmt.Printf("imported %d records\n", done)

	time.Sleep(cleanup) // flush files, close connections, ...

	switch {
	case err == nil:
		return 0
	case errors.Is(err, context.Canceled):
		return 130 // 128 + SIGINT, the shell convention for "stopped by Ctrl-C"
	default:
		fmt.Fprintln(os.Stderr, "shelf:", err)
		return 1
	}
}

// importRecords handles one record at a time and checks for cancellation
// between records, never in the middle of one.
func importRecords(ctx context.Context, n int) (int, error) {
	for i := 0; i < n; i++ {
		if err := ctx.Err(); err != nil {
			return i, context.Cause(ctx)
		}
		time.Sleep(100 * time.Millisecond) // the real work
	}
	return n, nil
}

$ ./shutdown & pid=$!; sleep 0.45; kill -INT $pid; wait $pid; echo "status $?"
importing
shelf: interrupted, finishing the current record (press Ctrl-C again to force quit)
imported 5 records
status 130
$ ./shutdown
importing
imported 20 records
status 0

$ ./shutdown -cleanup 3s & pid=$!; sleep 0.45; kill -TERM $pid; sleep 0.3; kill -TERM $pid; { wait $pid; } 2>/dev/null; echo "status $?"
importing
shelf: interrupted, finishing the current record (press Ctrl-C again to force quit)
imported 5 records
status 143

package main

import (
	"bufio"
	"errors"
	"fmt"
	"os"
	"os/exec"
	"strings"
)

func main() {
	// Output runs the command and returns its standard output.
	out, err := exec.Command("echo", "hello", "shelf").Output()
	fmt.Printf("Output: %q err=%v\n", out, err)

	// There is no shell: $HOME and * are passed through literally.
	out, _ = exec.Command("echo", "$HOME", "*.go").Output()
	fmt.Printf("no shell: %q\n", out)
	out, _ = exec.Command("sh", "-c", `echo "$1"`, "sh", "an argument; rm -rf / is just text").Output()
	fmt.Printf("sh -c with $1: %q\n", out)

	// A non-zero exit status becomes *exec.ExitError.
	_, err = exec.Command("sh", "-c", "echo oops >&2; exit 3").Output()
	var ee *exec.ExitError
	if errors.As(err, &ee) {
		fmt.Printf("ExitError: %v, code=%d, success=%t, stderr=%q\n", ee, ee.ExitCode(), ee.Success(), ee.Stderr)
	}

	// CombinedOutput interleaves stdout and stderr into one buffer.
	out, err = exec.Command("sh", "-c", "echo to-stdout; echo to-stderr >&2").CombinedOutput()
	fmt.Printf("CombinedOutput: %q err=%v\n", out, err)

	// Stdin: any io.Reader. Env and Dir configure the child.
	cmd := exec.Command("tr", "a-z", "A-Z")
	cmd.Stdin = strings.NewReader("the go programming language\n")
	out, _ = cmd.Output()
	fmt.Printf("stdin: %q\n", out)

	cmd = exec.Command("sh", "-c", `echo "mode=$SHELF_MODE dir=$(basename "$PWD")"`)
	cmd.Env = append(os.Environ(), "SHELF_MODE=readonly")
	cmd.Dir = "/usr"
	out, _ = cmd.Output()
	fmt.Printf("env and dir: %q\n", out)

	// Streaming: StdoutPipe, Start, read, then Wait (never Run with a pipe).
	cmd = exec.Command("sh", "-c", "for i in 1 2 3; do echo record-$i; done")
	stdout, err := cmd.StdoutPipe()
	if err != nil {
		panic(err)
	}
	if err := cmd.Start(); err != nil {
		panic(err)
	}
	sc := bufio.NewScanner(stdout)
	for sc.Scan() {
		fmt.Println("streamed:", sc.Text())
	}
	if err := cmd.Wait(); err != nil {
		panic(err)
	}
	fmt.Println("String():", cmd.String())
	fmt.Println("state:", cmd.ProcessState)
}

$ ./execbasics
Output: "hello shelf\n" err=<nil>
no shell: "$HOME *.go\n"
sh -c with $1: "an argument; rm -rf / is just text\n"
ExitError: exit status 3, code=3, success=false, stderr="oops\n"
CombinedOutput: "to-stdout\nto-stderr\n" err=<nil>
stdin: "THE GO PROGRAMMING LANGUAGE\n"
env and dir: "mode=readonly dir=usr\n"
streamed: record-1
streamed: record-2
streamed: record-3
String(): /bin/sh -c for i in 1 2 3; do echo record-$i; done
state: exit status 0

$ ./execreuse
first:  "once\n" <nil>
second: exec: Stdout already set

package main

import (
	"errors"
	"fmt"
	"os"
	"os/exec"
)

func main() {
	// A tiny executable in a fresh directory, which becomes the working
	// directory, and a PATH that contains "." (an explicit relative entry).
	dir, err := os.MkdirTemp("", "shelf-exec")
	if err != nil {
		panic(err)
	}
	defer os.RemoveAll(dir)
	script := "#!/bin/sh\necho running the local tool\n"
	if err := os.WriteFile(dir+"/shelf-tool", []byte(script), 0o755); err != nil {
		panic(err)
	}
	if err := os.Chdir(dir); err != nil {
		panic(err)
	}
	os.Setenv("PATH", ".:/usr/bin:/bin")

	// 1. A name found only through ".": LookPath refuses and says why.
	path, err := exec.LookPath("shelf-tool")
	fmt.Printf("LookPath: path=%q\n  err=%v\n  ErrDot=%t NotFound=%t\n",
		path, err, errors.Is(err, exec.ErrDot), errors.Is(err, exec.ErrNotFound))

	// Command stores the same error in cmd.Err and Run reports it.
	cmd := exec.Command("shelf-tool")
	fmt.Printf("cmd.Err is ErrDot: %t\n", errors.Is(cmd.Err, exec.ErrDot))
	fmt.Println("Run:", cmd.Run())

	// 2. Say "./shelf-tool" when the current directory is what you mean.
	out, err := exec.Command("./shelf-tool").Output()
	fmt.Printf("explicit path: %q err=%v\n", out, err)

	// 3. A name that is nowhere on PATH.
	_, err = exec.LookPath("no-such-tool")
	var pe *exec.Error
	fmt.Printf("missing: %v\n  ErrNotFound=%t, *exec.Error=%t\n",
		err, errors.Is(err, exec.ErrNotFound), errors.As(err, &pe))
}

$ ./execdot
LookPath: path="shelf-tool"
  err=exec: "shelf-tool": cannot run executable found relative to current directory
  ErrDot=true NotFound=false
cmd.Err is ErrDot: true
Run: exec: "shelf-tool": cannot run executable found relative to current directory
explicit path: "running the local tool\n" err=<nil>
missing: exec: "no-such-tool": executable file not found in $PATH
  ErrNotFound=true, *exec.Error=true
$ GODEBUG=execerrdot=0 ./execdot | head -3
LookPath: path="shelf-tool"
  err=<nil>
  ErrDot=false NotFound=false

package main

import (
	"bytes"
	"context"
	"errors"
	"fmt"
	"os"
	"os/exec"
	"syscall"
	"time"
)

func timed(name string, f func() error) {
	start := time.Now()
	err := f()
	fmt.Printf("%-22s err=%v (about %s)\n", name, err, time.Since(start).Round(100*time.Millisecond))
}

func main() {
	// 1. Default: the context deadline kills the process.
	timed("default (Kill)", func() error {
		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
		defer cancel()
		return exec.CommandContext(ctx, "sleep", "30").Run()
	})

	// 2. A custom Cancel asks politely with SIGTERM. The script handles it and
	// exits 0, yet Wait still reports the context error, because the command
	// was cancelled.
	timed("Cancel with SIGTERM", func() error {
		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
		defer cancel()
		cmd := exec.CommandContext(ctx, "sh", "-c", `trap 'echo cleaning up; exit 0' TERM; sleep 30 & wait`)
		cmd.Stdout = os.Stdout
		cmd.Cancel = func() error { return cmd.Process.Signal(syscall.SIGTERM) }
		return cmd.Run()
	})

	// 3. A child that outlives its parent keeps the output pipe open, so Wait
	// blocks until it exits. WaitDelay bounds that wait.
	slowStart := `sleep 2 & echo started`
	for _, delay := range []time.Duration{0, 300 * time.Millisecond} {
		timed(fmt.Sprintf("WaitDelay=%v", delay), func() error {
			var out bytes.Buffer
			cmd := exec.Command("sh", "-c", slowStart)
			cmd.Stdout = &out // not an *os.File, so Go copies it through a pipe
			cmd.WaitDelay = delay
			err := cmd.Run()
			if errors.Is(err, exec.ErrWaitDelay) {
				fmt.Printf("  output so far: %q\n", out.String())
			}
			return err
		})
	}

	// 4. A process that ignores SIGTERM: Cancel is tried first, and WaitDelay
	// escalates to Kill.
	timed("ignores TERM + delay", func() error {
		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
		defer cancel()
		cmd := exec.CommandContext(ctx, "sh", "-c", `trap '' TERM; while :; do sleep 1; done`)
		cmd.Cancel = func() error { return cmd.Process.Signal(syscall.SIGTERM) }
		cmd.WaitDelay = 300 * time.Millisecond
		return cmd.Run()
	})
}

$ ./execctx
default (Kill)         err=signal: killed (about 200ms)
cleaning up
Cancel with SIGTERM    err=context deadline exceeded (about 200ms)
WaitDelay=0s           err=<nil> (about 2s)
  output so far: "started\n"
WaitDelay=300ms        err=exec: WaitDelay expired before I/O complete (about 300ms)
ignores TERM + delay   err=signal: killed (about 500ms)

// Command shelf manages a small library catalogue stored in a JSON file.
package main

import (
	"context"
	"os"
	"os/signal"
	"syscall"
)

// version is set at link time: go build -ldflags "-X main.version=v1.4.0".
var version = "dev"

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	a := &app{
		stdin:  os.Stdin,
		stdout: os.Stdout,
		stderr: os.Stderr,
		getenv: os.Getenv,
	}
	code := run(ctx, os.Args[1:], a)
	stop() // os.Exit skips deferred calls, so release the signal handlers first
	os.Exit(code)
}

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io/fs"
	"os"
	"path/filepath"
	"slices"

	"example.com/shelf/catalog"
)

var (
	errNotFound  = errors.New("no such book")
	errOnLoan    = errors.New("book is already on loan")
	errNotOnLoan = errors.New("book is not on loan")
)

// library is the document stored on disk.
type library struct {
	Books []catalog.Book `json:"books"`
	Loans []catalog.Loan `json:"loans"`
}

// load reads the library file; a missing file is an empty library.
func load(path string) (*library, error) {
	data, err := os.ReadFile(path)
	if errors.Is(err, fs.ErrNotExist) {
		return &library{}, nil
	}
	if err != nil {
		return nil, err
	}
	var lib library
	if err := json.Unmarshal(data, &lib); err != nil {
		return nil, fmt.Errorf("%s: %w", path, err)
	}
	return &lib, nil
}

// save writes the library atomically: a temporary file in the same directory,
// then a rename, so a crash never leaves a half-written catalogue.
func (l *library) save(path string) error {
	data, err := json.MarshalIndent(l, "", "  ")
	if err != nil {
		return err
	}
	tmp, err := os.CreateTemp(filepath.Dir(path), ".shelf-*.tmp")
	if err != nil {
		return err
	}
	defer os.Remove(tmp.Name()) // harmless after a successful rename
	if _, err := tmp.Write(append(data, '\n')); err != nil {
		tmp.Close()
		return err
	}
	if err := tmp.Close(); err != nil {
		return err
	}
	return os.Rename(tmp.Name(), path)
}

func (l *library) find(isbn catalog.ISBN) (int, bool) {
	return slices.BinarySearchFunc(l.Books, isbn, func(b catalog.Book, id catalog.ISBN) int {
		switch {
		case b.ISBN < id:
			return -1
		case b.ISBN > id:
			return 1
		}
		return 0
	})
}

// put inserts or replaces a book, keeping Books sorted by ISBN.
func (l *library) put(b catalog.Book) {
	i, ok := l.find(b.ISBN)
	if ok {
		l.Books[i] = b
		return
	}
	l.Books = slices.Insert(l.Books, i, b)
}

func (l *library) loanIndex(isbn catalog.ISBN) int {
	return slices.IndexFunc(l.Loans, func(ln catalog.Loan) bool { return ln.Book == isbn })
}

func (l *library) lend(isbn catalog.ISBN, member string) error {
	if _, ok := l.find(isbn); !ok {
		return fmt.Errorf("%s: %w", isbn, errNotFound)
	}
	if l.loanIndex(isbn) >= 0 {
		return fmt.Errorf("%s: %w", isbn, errOnLoan)
	}
	l.Loans = append(l.Loans, catalog.Loan{Book: isbn, Member: member, State: catalog.OnLoan})
	return nil
}

func (l *library) giveBack(isbn catalog.ISBN) error {
	i := l.loanIndex(isbn)
	if i < 0 {
		return fmt.Errorf("%s: %w", isbn, errNotOnLoan)
	}
	l.Loans = slices.Delete(l.Loans, i, i+1)
	return nil
}

package main

import (
	"context"
	"encoding/json"
	"errors"
	"flag"
	"fmt"
	"io"
	"os"
	"runtime/debug"
	"strings"
	"text/tabwriter"

	"example.com/shelf/catalog"
	"example.com/shelf/internal/textutil"
)

// Exit statuses. 0 and 1 are universal; 2 is the convention for usage errors
// (it is also what the flag package and the Go runtime use).
const (
	exitOK          = 0
	exitFailure     = 1
	exitUsage       = 2
	exitRefused     = 3 // the catalogue rules said no: unknown book, already on loan
	exitInterrupted = 130
)

// app holds everything a command touches outside the process: tests replace it.
type app struct {
	stdin          io.Reader
	stdout, stderr io.Writer
	getenv         func(string) string
}

// errUsage means the problem has already been reported to the user.
var errUsage = errors.New("usage error")

type command struct {
	summary string
	run     func(ctx context.Context, a *app, lib string, args []string) error
}

var commands = map[string]command{
	"add":    {"add or replace a book", cmdAdd},
	"search": {"search by title or author", cmdSearch},
	"lend":   {"lend a book to a member", cmdLend},
	"return": {"return a book", cmdReturn},
	"import": {"import books from JSON (file or -)", cmdImport},
	"export": {"export books as JSON", cmdExport},
}

func run(ctx context.Context, args []string, a *app) int {
	global := flag.NewFlagSet("shelf", flag.ContinueOnError)
	global.SetOutput(a.stderr)
	data := global.String("data", "", "path of the library `file` (default $SHELF_DATA, then ./shelf.json)")
	showVersion := global.Bool("version", false, "print the version and exit")
	global.Usage = func() { usage(global, a.stderr) }

	if err := global.Parse(args); err != nil {
		if errors.Is(err, flag.ErrHelp) {
			return exitOK
		}
		return exitUsage
	}
	if *showVersion {
		fmt.Fprintln(a.stdout, versionString())
		return exitOK
	}

	rest := global.Args()
	if len(rest) == 0 {
		global.Usage()
		return exitUsage
	}
	cmd, ok := commands[rest[0]]
	if !ok {
		fmt.Fprintf(a.stderr, "shelf: unknown command %q\n", rest[0])
		global.Usage()
		return exitUsage
	}

	// Precedence: flag, then environment, then default.
	path := *data
	if path == "" {
		path = a.getenv("SHELF_DATA")
	}
	if path == "" {
		path = "shelf.json"
	}

	err := cmd.run(ctx, a, path, rest[1:])
	switch {
	case err == nil, errors.Is(err, flag.ErrHelp):
		return exitOK
	case errors.Is(err, errUsage):
		return exitUsage
	case errors.Is(err, context.Canceled):
		fmt.Fprintf(a.stderr, "shelf %s: interrupted\n", rest[0])
		return exitInterrupted
	case errors.Is(err, errNotFound), errors.Is(err, errOnLoan), errors.Is(err, errNotOnLoan):
		fmt.Fprintf(a.stderr, "shelf %s: %v\n", rest[0], err)
		return exitRefused
	default:
		fmt.Fprintf(a.stderr, "shelf %s: %v\n", rest[0], err)
		return exitFailure
	}
}

func usage(global *flag.FlagSet, w io.Writer) {
	fmt.Fprintln(w, "usage: shelf [-data file] <command> [flags] [args]")
	fmt.Fprintln(w, "\ncommands:")
	for _, name := range []string{"add", "search", "lend", "return", "import", "export"} {
		fmt.Fprintf(w, "  %-8s %s\n", name, commands[name].summary)
	}
	fmt.Fprintln(w, "\nglobal flags:")
	global.SetOutput(w)
	global.PrintDefaults()
}

func versionString() string {
	v := version
	if bi, ok := debug.ReadBuildInfo(); ok && v == "dev" && bi.Main.Version != "" && bi.Main.Version != "(devel)" {
		v = bi.Main.Version
	}
	return "shelf " + v
}

// newFlags returns a FlagSet whose messages go to stderr and whose parse
// failures are reported once, as errUsage.
func newFlags(a *app, name string) *flag.FlagSet {
	fs := flag.NewFlagSet("shelf "+name, flag.ContinueOnError)
	fs.SetOutput(a.stderr)
	return fs
}

func parse(fs *flag.FlagSet, args []string) error {
	if err := fs.Parse(args); err != nil {
		if errors.Is(err, flag.ErrHelp) {
			return err
		}
		return errUsage
	}
	return nil
}

func usageErr(a *app, format string, v ...any) error {
	fmt.Fprintf(a.stderr, "shelf: "+format+"\n", v...)
	return errUsage
}

// authors is a repeatable -author flag.
type authors []string

func (s *authors) String() string     { return strings.Join(*s, ", ") }
func (s *authors) Set(v string) error { *s = append(*s, v); return nil }

func cmdAdd(_ context.Context, a *app, path string, args []string) error {
	fs := newFlags(a, "add")
	isbn := fs.String("isbn", "", "ISBN-13 of the book (required)")
	title := fs.String("title", "", "title (required)")
	var by authors
	fs.Var(&by, "author", "author `name` (repeatable)")
	if err := parse(fs, args); err != nil {
		return err
	}
	id, err := catalog.ParseISBN(*isbn)
	if err != nil {
		return usageErr(a, "%v", err)
	}
	if strings.TrimSpace(*title) == "" {
		return usageErr(a, "add: -title is required")
	}
	book := catalog.Book{ISBN: id, Title: strings.TrimSpace(*title)}
	for _, n := range by {
		book.Authors = append(book.Authors, catalog.Author{Name: n})
	}

	lib, err := load(path)
	if err != nil {
		return err
	}
	lib.put(book)
	if err := lib.save(path); err != nil {
		return err
	}
	fmt.Fprintf(a.stdout, "added %s %q\n", book.ISBN, book.Title)
	return nil
}

func cmdSearch(_ context.Context, a *app, path string, args []string) error {
	fs := newFlags(a, "search")
	asJSON := fs.Bool("json", false, "print the matches as JSON")
	limit := fs.Int("limit", 20, "maximum number of results")
	if err := parse(fs, args); err != nil {
		return err
	}
	query := textutil.Normalize(strings.Join(fs.Args(), " "))

	lib, err := load(path)
	if err != nil {
		return err
	}
	found := []catalog.Book{} // not nil: a nil slice would encode as null
	for _, b := range lib.Books {
		if matches(b, query) {
			found = append(found, b)
			if len(found) == *limit {
				break
			}
		}
	}

	if *asJSON {
		enc := json.NewEncoder(a.stdout)
		enc.SetIndent("", "  ")
		return enc.Encode(found)
	}
	tw := tabwriter.NewWriter(a.stdout, 0, 8, 2, ' ', 0)
	for _, b := range found {
		status := catalog.Available
		if lib.loanIndex(b.ISBN) >= 0 {
			status = catalog.OnLoan
		}
		fmt.Fprintf(tw, "%s\t%s\t%s\n", b.ISBN, b.Title, status)
	}
	if err := tw.Flush(); err != nil {
		return err
	}
	if len(found) == 0 {
		fmt.Fprintln(a.stderr, "shelf: no matches") // diagnostics go to stderr, data to stdout
	}
	return nil
}

func matches(b catalog.Book, query string) bool {
	if strings.Contains(textutil.Normalize(b.Title), query) {
		return true
	}
	for _, au := range b.Authors {
		if strings.Contains(textutil.Normalize(au.Name), query) {
			return true
		}
	}
	return false
}

func cmdLend(_ context.Context, a *app, path string, args []string) error {
	fs := newFlags(a, "lend")
	member := fs.String("member", "", "member `id` (required)")
	if err := parse(fs, args); err != nil {
		return err
	}
	if *member == "" || fs.NArg() != 1 {
		return usageErr(a, "lend needs -member and exactly one ISBN")
	}
	isbn, err := catalog.ParseISBN(fs.Arg(0))
	if err != nil {
		return usageErr(a, "%v", err)
	}
	lib, err := load(path)
	if err != nil {
		return err
	}
	if err := lib.lend(isbn, *member); err != nil {
		return err
	}
	if err := lib.save(path); err != nil {
		return err
	}
	fmt.Fprintf(a.stdout, "lent %s to %s\n", isbn, *member)
	return nil
}

func cmdReturn(_ context.Context, a *app, path string, args []string) error {
	fs := newFlags(a, "return")
	if err := parse(fs, args); err != nil {
		return err
	}
	if fs.NArg() != 1 {
		return usageErr(a, "return needs exactly one ISBN")
	}
	isbn, err := catalog.ParseISBN(fs.Arg(0))
	if err != nil {
		return usageErr(a, "%v", err)
	}
	lib, err := load(path)
	if err != nil {
		return err
	}
	if err := lib.giveBack(isbn); err != nil {
		return err
	}
	if err := lib.save(path); err != nil {
		return err
	}
	fmt.Fprintf(a.stdout, "returned %s\n", isbn)
	return nil
}

// cmdImport reads a JSON array of books from a file, or from standard input
// when the argument is "-" or missing and input is piped in.
func cmdImport(ctx context.Context, a *app, path string, args []string) error {
	fs := newFlags(a, "import")
	if err := parse(fs, args); err != nil {
		return err
	}
	var in io.Reader = a.stdin
	switch {
	case fs.NArg() > 1:
		return usageErr(a, "import takes at most one file (or -)")
	case fs.NArg() == 1 && fs.Arg(0) != "-":
		f, err := os.Open(fs.Arg(0))
		if err != nil {
			return err
		}
		defer f.Close()
		in = f
	}

	var books []catalog.Book
	if err := json.NewDecoder(in).Decode(&books); err != nil {
		return fmt.Errorf("reading JSON: %w", err)
	}
	lib, err := load(path)
	if err != nil {
		return err
	}
	for i, b := range books {
		if err := ctx.Err(); err != nil { // stop between records, never in the middle of one
			return err
		}
		if _, err := catalog.ParseISBN(string(b.ISBN)); err != nil {
			return fmt.Errorf("record %d: %w", i+1, err)
		}
		lib.put(b)
	}
	if err := lib.save(path); err != nil {
		return err
	}
	fmt.Fprintf(a.stdout, "imported %d books\n", len(books))
	return nil
}

func cmdExport(_ context.Context, a *app, path string, args []string) (err error) {
	fs := newFlags(a, "export")
	out := fs.String("o", "-", "write to `file` instead of standard output")
	if err := parse(fs, args); err != nil {
		return err
	}
	lib, err := load(path)
	if err != nil {
		return err
	}

	w := a.stdout
	if *out != "-" {
		f, err := os.Create(*out)
		if err != nil {
			return err
		}
		defer func() {
			// The Close error of a file opened for writing is the last chance
			// to learn that the data did not reach the disk.
			if cerr := f.Close(); cerr != nil && err == nil {
				err = cerr
			}
		}()
		w = f
	}
	enc := json.NewEncoder(w)
	enc.SetIndent("", "  ")
	return enc.Encode(lib.Books)
}

$ shelf -version
shelf v1.4.0
$ shelf add -isbn 978-0-13-419044-0 -title "The Go Programming Language" -author "Alan Donovan" -author "Brian Kernighan"
added 9780134190440 "The Go Programming Language"
$ shelf add -isbn 978-0-13-468599-1 -title "The Pragmatic Programmer" -author "David Thomas"
added 9780134685991 "The Pragmatic Programmer"
$ shelf add -isbn 978-1-4919-3-8 -title "Bad ISBN"
shelf: catalog: invalid ISBN: "978-1-4919-3-8"
[exit status 2]
$ shelf search go
9780134190440  The Go Programming Language  available
$ shelf search -json donovan
[
  {
    "ISBN": "9780134190440",
    "Title": "The Go Programming Language",
    "Authors": [
      {
        "Name": "Alan Donovan"
      },
      {
        "Name": "Brian Kernighan"
      }
    ]
  }
]
$ shelf search zzz; echo "status $?"; shelf search -json zzz
shelf: no matches
status 0
[]

$ shelf lend -member ana 978-0-13-419044-0
lent 9780134190440 to ana
$ shelf lend -member bob 978-0-13-419044-0
shelf lend: 9780134190440: book is already on loan
[exit status 3]
$ shelf search programming
9780134190440  The Go Programming Language  on loan
$ shelf return 978-0-13-419044-0
returned 9780134190440
$ shelf return 978-0-13-419044-0
shelf return: 9780134190440: book is not on loan
[exit status 3]
$ shelf lend 978-0-13-419044-0
shelf: lend needs -member and exactly one ISBN
[exit status 2]
$ shelf frobnicate
shelf: unknown command "frobnicate"
usage: shelf [-data file] <command> [flags] [args]

commands:
  add      add or replace a book
  search   search by title or author
  lend     lend a book to a member
  return   return a book
  import   import books from JSON (file or -)
  export   export books as JSON

global flags:
  -data file
    	path of the library file (default $SHELF_DATA, then ./shelf.json)
  -version
    	print the version and exit
[exit status 2]

$ shelf search -limit
flag needs an argument: -limit
Usage of shelf search:
  -json
    	print the matches as JSON
  -limit int
    	maximum number of results (default 20)
[exit status 2]
$ shelf -h
usage: shelf [-data file] <command> [flags] [args]

commands:
  add      add or replace a book
  search   search by title or author
  lend     lend a book to a member
  return   return a book
  import   import books from JSON (file or -)
  export   export books as JSON

global flags:
  -data file
    	path of the library file (default $SHELF_DATA, then ./shelf.json)
  -version
    	print the version and exit

$ shelf export -o books.json && head -8 books.json
[
  {
    "ISBN": "9780134190440",
    "Title": "The Go Programming Language",
    "Authors": [
      {
        "Name": "Alan Donovan"
      },
$ shelf export | shelf -data copy.json import -
imported 2 books
$ echo "[{\"ISBN\":\"123\"}]" | shelf -data copy.json import
shelf import: record 1: catalog: invalid ISBN: "123"
[exit status 1]
$ echo "not json" | shelf -data copy.json import
shelf import: reading JSON: invalid character 'o' in literal null (expecting 'u')
[exit status 1]
$ shelf import missing.json
shelf import: open missing.json: no such file or directory
[exit status 1]
$ SHELF_DATA=copy.json shelf search kernighan
9780134190440  The Go Programming Language  available
$ shelf -data /no/such/dir/x.json add -isbn 978-0-13-419044-0 -title t
shelf add: open /no/such/dir/.shelf-1046778161.tmp: no such file or directory
[exit status 1]
$ ls -A
books.json
copy.json
shelf.json

package main

import (
	"bytes"
	"context"
	"path/filepath"
	"strings"
	"testing"
)

// runShelf runs the CLI in-process with fake streams and environment.
func runShelf(t *testing.T, ctx context.Context, stdin string, env map[string]string, args ...string) (code int, stdout, stderr string) {
	t.Helper()
	var out, errb bytes.Buffer
	a := &app{
		stdin:  strings.NewReader(stdin),
		stdout: &out,
		stderr: &errb,
		getenv: func(k string) string { return env[k] },
	}
	code = run(ctx, args, a)
	return code, out.String(), errb.String()
}

func TestExitCodes(t *testing.T) {
	data := filepath.Join(t.TempDir(), "lib.json")
	const isbn = "978-0-13-419044-0"

	tests := []struct {
		name     string
		args     []string
		wantCode int
		wantErr  string // substring of stderr
	}{
		{"add", []string{"-data", data, "add", "-isbn", isbn, "-title", "TGPL"}, exitOK, ""},
		{"lend", []string{"-data", data, "lend", "-member", "ana", isbn}, exitOK, ""},
		{"lend twice", []string{"-data", data, "lend", "-member", "bob", isbn}, exitRefused, "already on loan"},
		{"bad isbn", []string{"-data", data, "lend", "-member", "ana", "123"}, exitUsage, "invalid ISBN"},
		{"missing member", []string{"-data", data, "lend", isbn}, exitUsage, "lend needs"},
		{"unknown command", []string{"-data", data, "frob"}, exitUsage, "unknown command"},
		{"unknown flag", []string{"-nope"}, exitUsage, "not defined"},
		{"no command", nil, exitUsage, "usage: shelf"},
		{"help", []string{"-h"}, exitOK, "usage: shelf"},
		{"return", []string{"-data", data, "return", isbn}, exitOK, ""},
		{"return twice", []string{"-data", data, "return", isbn}, exitRefused, "not on loan"},
	}
	for _, tc := range tests {
		code, _, stderr := runShelf(t, t.Context(), "", nil, tc.args...)
		if code != tc.wantCode {
			t.Errorf("%s: exit code = %d, want %d (stderr %q)", tc.name, code, tc.wantCode, stderr)
		}
		if !strings.Contains(stderr, tc.wantErr) {
			t.Errorf("%s: stderr = %q, want it to contain %q", tc.name, stderr, tc.wantErr)
		}
	}
}

func TestDataPathPrecedence(t *testing.T) {
	dir := t.TempDir()
	fromEnv := filepath.Join(dir, "env.json")
	fromFlag := filepath.Join(dir, "flag.json")
	const isbn = "978-0-13-419044-0"
	env := map[string]string{"SHELF_DATA": fromEnv}

	runShelf(t, t.Context(), "", env, "add", "-isbn", isbn, "-title", "In env file")
	runShelf(t, t.Context(), "", env, "-data", fromFlag, "add", "-isbn", isbn, "-title", "In flag file")

	_, out, _ := runShelf(t, t.Context(), "", nil, "-data", fromEnv, "search", "env")
	if !strings.Contains(out, "In env file") {
		t.Errorf("env file search = %q", out)
	}
	_, out, _ = runShelf(t, t.Context(), "", nil, "-data", fromFlag, "search", "flag")
	if !strings.Contains(out, "In flag file") {
		t.Errorf("flag file search = %q", out)
	}
}

func TestImportFromStdinAndInterrupt(t *testing.T) {
	data := filepath.Join(t.TempDir(), "lib.json")
	input := `[{"ISBN":"9780134190440","Title":"TGPL"}]`

	code, out, _ := runShelf(t, t.Context(), input, nil, "-data", data, "import", "-")
	if code != exitOK || !strings.Contains(out, "imported 1 books") {
		t.Fatalf("import: code=%d out=%q", code, out)
	}

	// A context that is already cancelled models Ctrl-C arriving mid-import.
	ctx, cancel := context.WithCancel(t.Context())
	cancel()
	code, _, stderr := runShelf(t, ctx, input, nil, "-data", data, "import", "-")
	if code != exitInterrupted {
		t.Errorf("interrupted import: code=%d stderr=%q", code, stderr)
	}

	code, _, stderr = runShelf(t, t.Context(), `[{"ISBN":"123"}]`, nil, "-data", data, "import")
	if code != exitFailure || !strings.Contains(stderr, "record 1") {
		t.Errorf("bad record: code=%d stderr=%q", code, stderr)
	}
}

=== RUN   TestExitCodes
--- PASS: TestExitCodes (0.00s)
=== RUN   TestDataPathPrecedence
--- PASS: TestDataPathPrecedence (0.00s)
=== RUN   TestImportFromStdinAndInterrupt
--- PASS: TestImportFromStdinAndInterrupt (0.00s)
PASS
ok  	example.com/shelf/cmd/shelf	0.175s

ok  	example.com/shelf/cmd/shelf	1.206s	coverage: 65.9% of statements