sh_machine.go

// Code generated by go generate; DO NOT EDIT.
// This file is generated from lesiw.io/command package helper functions.

package command

import (
	"context"
	"io"
)

// The methods below are convenience wrappers that delegate to lesiw.io/command
// package-level helper functions. These are kept in sync with lesiw.io/command
// via code generation to ensure Sh provides ergonomic access to all
//
// command operations.

// Do executes a command for its side effects, discarding output.
// Only the error status is returned.
//
// If the command fails, the error will contain exit code and log output.
//
// This is a convenience method that calls [Do].
func (sh *Sh) Do(
	ctx context.Context, args ...string,
) error {
	return Do(ctx, sh, args...)
}

// Exec executes a command and waits for it to complete.
// The command's output is attached to the controlling terminal.
//
// Unlike Read, errors returned by Exec will not include log output.
//
// This is a convenience method that calls [Exec].
func (sh *Sh) Exec(
	ctx context.Context, args ...string,
) error {
	return Exec(ctx, sh, args...)
}

// NewFilter creates a bidirectional command filter with full
// Read/Write/Close access.
//
// The returned io.ReadWriteCloser provides direct access to the command's
// stdin (Write), stdout (Read), and stdin close signal (Close).
//
// If the underlying command does not support writing (is read-only), Write()
// will return an error. Close() closes stdin if supported, otherwise it is
// a no-op.
//
// NewFilter is primarily useful with command.Copy for pipeline composition.
// For most use cases, prefer NewReader (read-only with cancellation) or
// NewWriter (write-only with completion wait).
//
// This is a convenience method that calls [NewFilter].
func (sh *Sh) NewFilter(
	ctx context.Context, args ...string,
) io.ReadWriteCloser {
	return NewFilter(ctx, sh, args...)
}

// NewReader creates a read-only command that cancels on Close.
//
// The command starts lazily on the first Read() call. Close() cancels
// the underlying context to immediately terminate the command, which is
// appropriate for read-only operations where the user has signaled
// they're done reading.
//
// If Close() is called before any Read(), the command never starts.
//
// This is a convenience method that calls [NewReader].
func (sh *Sh) NewReader(
	ctx context.Context, args ...string,
) io.ReadCloser {
	return NewReader(ctx, sh, args...)
}

// NewWriter creates a write-only command that waits for completion on Close.
//
// The command starts lazily on the first Write() call. Close() waits for
// the command to complete gracefully by closing stdin and reading any output,
// which is appropriate for write-only operations that must finish processing
// before the operation is considered complete.
//
// If Close() is called before any Write(), the command never starts.
//
// NewWriter implements io.ReaderFrom for optimized copying. When io.Copy
// detects this, it will auto-close stdin after the source reaches EOF.
//
// This is a convenience method that calls [NewWriter].
func (sh *Sh) NewWriter(
	ctx context.Context, args ...string,
) io.WriteCloser {
	return NewWriter(ctx, sh, args...)
}

// Read executes a command and returns its output as a string.
// Trailing newlines are stripped from the output.
// For exact output, use [io.ReadAll].
//
// If the command fails, the error will contain an exit code and log output.
//
// This is a convenience method that calls [Read].
func (sh *Sh) Read(
	ctx context.Context, args ...string,
) (string, error) {
	return Read(ctx, sh, args...)
}