Documentation
¶
Overview ¶
Package exec provides a client and interface for executing external commands. It abstracts the underlying os/exec calls, allowing for easier testing and consistent command execution logic throughout the application.
The primary components are:
- CommandExecutor: An interface defining methods to run commands and capture output.
- OSCommandExecutor: The default implementation of CommandExecutor using os/exec.
- ExecutorClient: A client that uses a CommandExecutor to provide higher-level methods for command execution.
Usage:
// In your application setup (e.g., cmd/root.go or per command)
osExecutor := exec.NewOSCommandExecutor(someLogger) // Pass an *slog.Logger
execClient := exec.NewClient(osExecutor)
// Later, to run a command:
err := execClient.Execute(ctx, "/tmp", "ls", "-l")
if err != nil {
// handle error
}
// To capture output:
stdout, stderr, err := execClient.CaptureOutput(ctx, ".", "go", "version")
if err != nil {
// handle error
}
fmt.Printf("Go version: %s", stdout)
Index ¶
- type CommandExecutor
- type ExecutorClient
- func (c *ExecutorClient) CaptureOutput(ctx context.Context, dir string, commandName string, args ...string) (string, string, error)
- func (c *ExecutorClient) CommandExists(commandName string) bool
- func (c *ExecutorClient) Execute(ctx context.Context, dir string, commandName string, args ...string) error
- func (c *ExecutorClient) Logger() *slog.Logger
- func (c *ExecutorClient) UnderlyingExecutor() CommandExecutor
- type OSCommandExecutor
- func (e *OSCommandExecutor) CaptureOutput(ctx context.Context, dir string, commandName string, args ...string) (string, string, error)
- func (e *OSCommandExecutor) CommandExists(commandName string) bool
- func (e *OSCommandExecutor) Execute(ctx context.Context, dir string, commandName string, args ...string) error
- func (e *OSCommandExecutor) Logger() *slog.Logger
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CommandExecutor ¶
type CommandExecutor interface {
// Execute runs a command, connecting stdio to the parent process's stdio.
// dir: the working directory for the command.
// commandName: the name or path of the command to run.
// args: arguments for the command.
// Returns an error if execution fails.
Execute(ctx context.Context, dir string, commandName string, args ...string) error
// CaptureOutput runs a command, capturing its stdout and stderr.
// dir: the working directory for the command.
// commandName: the name or path of the command to run.
// args: arguments for the command.
// Returns stdout, stderr, and any error (including *exec.PkgExitError).
CaptureOutput(
ctx context.Context,
dir string,
commandName string,
args ...string,
) (stdout, stderr string, err error)
// CommandExists checks if a command is available in the PATH or at the specified path.
CommandExists(commandName string) bool
// Logger returns the logger associated with this executor.
Logger() *slog.Logger
}
CommandExecutor defines the interface for running external commands. Implementations of this interface handle the actual execution logic.
func NewOSCommandExecutor ¶
func NewOSCommandExecutor(logger *slog.Logger) CommandExecutor
NewOSCommandExecutor creates a new OSCommandExecutor. If logger is nil, a discard logger will be used.
type ExecutorClient ¶
type ExecutorClient struct {
// contains filtered or unexported fields
}
ExecutorClient provides a high-level interface for running external commands. It uses an underlying CommandExecutor for the actual execution.
func NewClient ¶
func NewClient(executor CommandExecutor) *ExecutorClient
NewClient creates a new ExecutorClient with the given CommandExecutor.
func (*ExecutorClient) CaptureOutput ¶
func (c *ExecutorClient) CaptureOutput( ctx context.Context, dir string, commandName string, args ...string, ) (string, string, error)
CaptureOutput runs a command and captures its stdout and stderr. See CommandExecutor.CaptureOutput.
func (*ExecutorClient) CommandExists ¶
func (c *ExecutorClient) CommandExists(commandName string) bool
CommandExists checks if a command is available. See CommandExecutor.CommandExists.
func (*ExecutorClient) Execute ¶
func (c *ExecutorClient) Execute( ctx context.Context, dir string, commandName string, args ...string, ) error
Execute runs a command, typically piping stdio. See CommandExecutor.Execute.
func (*ExecutorClient) Logger ¶
func (c *ExecutorClient) Logger() *slog.Logger
Logger returns the logger from the underlying executor.
func (*ExecutorClient) UnderlyingExecutor ¶ added in v0.1.1
func (c *ExecutorClient) UnderlyingExecutor() CommandExecutor
UnderlyingExecutor returns the CommandExecutor used by this client. This allows passing the raw executor to other components if needed.
type OSCommandExecutor ¶
type OSCommandExecutor struct {
// contains filtered or unexported fields
}
OSCommandExecutor is the default implementation of CommandExecutor using the os/exec package.
func (*OSCommandExecutor) CaptureOutput ¶
func (e *OSCommandExecutor) CaptureOutput( ctx context.Context, dir string, commandName string, args ...string, ) (string, string, error)
CaptureOutput runs a command and captures its output.
func (*OSCommandExecutor) CommandExists ¶
func (e *OSCommandExecutor) CommandExists(commandName string) bool
CommandExists checks if a command exists in the path.
func (*OSCommandExecutor) Execute ¶
func (e *OSCommandExecutor) Execute( ctx context.Context, dir string, commandName string, args ...string, ) error
Execute runs a command, piping stdio.
func (*OSCommandExecutor) Logger ¶
func (e *OSCommandExecutor) Logger() *slog.Logger
Logger returns the logger associated with this executor.
Source Files