Go library examples in docs don't work

[philrz]

Repro is with Zed commit 7ba4ecc.

I'm not much of a Go developer, but I was hacking a bit and tried working off the user-facing docs. However, what's shown there doesn't currently work. Starting with what's shown for just the top ZSON Reader example:

$ mkdir example

$ cd example

$ go mod init example
go: creating new go.mod: module example

$ cat > main.go
# [pasted the example from the docs]

$ go mod tidy
go: finding module for package github.com/brimdata/zed/zson
go: finding module for package github.com/brimdata/zed
go: finding module for package github.com/brimdata/zed/zio/zsonio
go: found github.com/brimdata/zed in github.com/brimdata/zed v1.8.1
go: found github.com/brimdata/zed/zio/zsonio in github.com/brimdata/zed v1.8.1
go: found github.com/brimdata/zed/zson in github.com/brimdata/zed v1.8.1

$ echo '{s:"hello"}{x:123}{s:"world"}' | go run .
# example
./main.go:15:32: cannot use os.Stdin (variable of type *os.File) as *"github.com/brimdata/zed".Context value in argument to zsonio.NewReader
./main.go:15:42: cannot use zctx (variable of type *"github.com/brimdata/zed".Context) as io.Reader value in argument to zsonio.NewReader: *"github.com/brimdata/zed".Context does not implement io.Reader (missing method Read)

[philrz]

I've verified this by working off the docs deployment triggered by Zed commit c014c91.

As a user, I can now successfully run through the Go library examples in the docs. The only two gotchas I experienced:

1. They're written with the current tip-of-main Zed in mind, but following the instructions as written will currently pull the last tagged Zed release v1.15.0 such that the examples fail when run. Therefore to test I manually updated the Zed dependency in the go.mod to a recent commit:

   require github.com/brimdata/zed v1.15.1-0.20240620170635-36a18e91a5d6
   

   ...and re-ran go mod tidy before running the example.

   This problem will go away when we tag the next GA Zed release.

2. Moving on to the second example required a re-run of go mod tidy, but that's a small change for which I've put up a proposed change in Mention the re-run of "go mod tidy" #5147.

Thanks @mattnibs!