I'm wondering if we actually need this. I mean, it's absolutely correct in the sense that this file isn't part of the script package. On the other hand, one thing about example programs is that people will copy and paste them exactly as is—that's what they're for, after all. Including this line would stop their program working, which might be very puzzling for beginners.

Does it do us any harm to omit the build tag in examples?

Good question — I tried it, and removing the build tag does break things: with both count_errors.go and filter_csv.go declaring func main() in the same examples/ directory, go build ./... and go vet ./... fail with "main redeclared". go run file.go handles one file fine, but a directory-wide build compiles them as one package, so the tag was working around exactly that.

To keep them copy-paste-able without the tag, my instinct is to give each example its own subdirectory (examples/count_errors/main.go, examples/filter_csv/main.go) — scales cleanly and go build ./... stays happy. But it's your call on the layout. Which would you prefer?

Yes, we're working against the grain of Go a little bit here, aren't we? It's actually quite awkward to include a copypastable program in a Go module that doesn't cause a main conflict.

Maybe what we should do instead is use Go's built-in example mechanism. For example (sorry), we could add this to script_test.go:

func Example_count_lines() {
	count, err := script.File("examples/app.log").Match("ERROR").CountLines()
	if err != nil {
		panic(err)
	}
	fmt.Printf("Number of ERROR lines: %d\n", count)
}

func Example_filter_csv() {
	// Column splits on whitespace, so turn the comma into a space first,
	// then take the first field (the server name).
	_, err := script.File("examples/servers.csv").Match("DOWN").Replace(",", " ").Column(1).Stdout()
	if err != nil {
		panic(err)
	}
}

As you probably know, because the function names start with Example, they'll be built as part of the autogenerated documentation, and because they don't include the names of any other identifier, they'll be treated as package-level examples:

We can put the data files in the testdata folder—I don't think the public pkgsite instance will let you read these, but that's okay. People can copy and paste the code and it'll work.