# Go workspace builder examples

Source: https://libtmux.org/en/go/latest/workspace/internals/examples/

> Internal examples for building and inspecting workspaces through the Go API.

These Go examples build a workspace on dedicated sockets and check their
printed results with `// Output:` assertions. Each example creates a deadline
and tears down its own server with an independent cleanup deadline.

## Build a session

`Example` parses YAML, builds the session, and searches its resulting windows.
[`ExampleBuildInto`](https://github.com/libtmux/libtmux-go/blob/5f808882015a975a65acc7f9da5b3ff0d5cbdc91/workspace/example_test.go) creates the initial session connection explicitly and
populates it through `BuildInto`. The final example checks an unknown field.

```go file="workspace/example_test.go"
package workspace_test

import (
	"context"
	"fmt"
	"time"

	"github.com/libtmux/libtmux-go/tmux"
	"github.com/libtmux/libtmux-go/workspace"
)

// Load a tmuxp-style document and build the session it describes.
func Example() {
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	server, err := tmux.NewServer(tmux.ServerOptions{
		SocketName: "libtmux-go-example-workspace",
	})
	if err != nil {
		fmt.Println("server:", err)
		return
	}
	defer killExampleServer(server)

	document := []byte(`
session_name: review
windows:
  - window_name: editor
    panes:
      - shell_command: printf 'ready\n'
  - window_name: tests
    panes:
      - shell_command: printf 'ready\n'
      - shell_command: printf 'ready\n'
`)
	parsed, err := workspace.Parse(document)
	if err != nil {
		fmt.Println("parse:", err)
		return
	}

	session, err := workspace.Build(ctx, server, parsed)
	if err != nil {
		fmt.Println("build:", err)
		return
	}

	name, _ := session.Name()
	windows, err := session.SearchWindows(ctx, nil)
	if err != nil {
		fmt.Println("search windows:", err)
		return
	}
	fmt.Println(name, len(windows))
	// Output: review 2
}

// Create the initial session, prefer a retained connection where tmux supports
// one, then populate the rest of the workspace through that session.
func ExampleBuildInto() {
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	server, err := tmux.NewServer(tmux.ServerOptions{
		SocketName: "libtmux-go-example-workspace-continue",
	})
	if err != nil {
		fmt.Println("server:", err)
		return
	}
	defer killExampleServer(server)

	described := workspace.Workspace{
		SessionName: "review",
		Windows: []workspace.Window{
			{Name: "editor", Panes: []workspace.Pane{{Shell: "sleep 60"}}},
			{Name: "tests", Panes: []workspace.Pane{{Shell: "sleep 60"}}},
		},
	}
	request, err := described.InitialSessionRequest()
	if err != nil {
		fmt.Println("request:", err)
		return
	}
	_, connection, err := server.NewSessionConnection(
		ctx,
		request,
		tmux.ConnectionOptions{},
	)
	if err != nil {
		fmt.Println("create:", err)
		return
	}
	defer func() { _ = connection.Close() }()
	session := connection.Session()
	if err := workspace.BuildInto(ctx, session, described); err != nil {
		fmt.Println("build:", err)
		return
	}
	windows, err := session.SearchWindows(ctx, nil)
	if err != nil {
		fmt.Println("search windows:", err)
		return
	}
	fmt.Println(len(windows))
	// Output: 2
}

// A misspelled key fails the parse rather than being dropped, so a workspace
// that does not do what its author meant says so before anything is built.
func ExampleParse_unknownField() {
	_, err := workspace.Parse([]byte("session_name: review\nwindow:\n  - {}\n"))
	fmt.Println(err != nil)
	// Output: true
}

// killExampleServer stops an example's server on a context of its own, since an
// example's own context may already be spent by the time it returns.
func killExampleServer(server tmux.Server) {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	_ = server.Kill(ctx)
}
```

Use the connection-owning example when you want to keep a transport available
for later operations. Use `Build` when construction should manage its own
temporary connection and return a normal session handle.

## Verification

From the workspace module in a prepared source checkout, run:

```console
$ go test -run Example .
```

Go's example runner executes these functions and compares their output with
the comments. tmux must be on the host. The page reads the source file during
the site build; that inclusion does not itself run the examples.

The names in these examples select dedicated servers. Avoid reusing those
socket names for unrelated work because the cleanup stops their servers.

[Example source](https://github.com/libtmux/libtmux-go/blob/5f808882015a975a65acc7f9da5b3ff0d5cbdc91/workspace/example_test.go)