Documentation
¶
Overview ¶
Package cmdexec provides a testable abstraction for running external commands.
Index ¶
- func WrapExitError(err error, stderr string) error
- type Executor
- type ExitError
- type LogFunc
- type LoggingExecutor
- func (l *LoggingExecutor) Run(ctx context.Context, name string, args ...string) (string, string, error)
- func (l *LoggingExecutor) RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (string, string, error)
- func (l *LoggingExecutor) Start(ctx context.Context, name string, args ...string) (*Process, error)
- type OSExecutor
- func (e *OSExecutor) Run(ctx context.Context, name string, args ...string) (string, string, error)
- func (e *OSExecutor) RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (string, string, error)
- func (e *OSExecutor) Start(ctx context.Context, name string, args ...string) (*Process, error)
- type Process
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WrapExitError ¶ added in v0.10.0
WrapExitError returns a bare *exec.ExitError as an *ExitError carrying stderr, and any other error unchanged. Executors call it on the result of a finished command; test doubles call it so that their errors have the same shape as the real ones.
Types ¶
type Executor ¶
type Executor interface {
// Run executes the named command with the given arguments and returns
// the captured stdout and stderr. If the command exits with a non-zero
// status, the returned error is an *ExitError that carries stderr and
// wraps the *exec.ExitError.
Run(ctx context.Context, name string, args ...string) (stdout string, stderr string, err error)
// RunWithStdin is like Run but pipes the given reader to the command's stdin.
RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (stdout string, stderr string, err error)
// Start starts a long-lived command and returns a Process for reading
// its stdout incrementally. The command is killed when ctx is cancelled.
// The caller must call Process.Close to release resources.
Start(ctx context.Context, name string, args ...string) (*Process, error)
}
Executor runs external commands and captures their output.
type ExitError ¶ added in v0.10.0
ExitError is the error of a command that ran and exited with a non-zero status. It keeps what the command wrote to stderr, which for docker is the only place that says what went wrong: "exit status 1" alone cannot tell a missing volume from one that is still in use.
func (*ExitError) Error ¶ added in v0.10.0
Error returns the exit status followed by the command's stderr, if any.
type LogFunc ¶
LogFunc is called before each command execution with the context and the full command string (name + args joined by spaces).
type LoggingExecutor ¶
LoggingExecutor wraps another Executor and calls a LogFunc before each command invocation.
func (*LoggingExecutor) Run ¶
func (l *LoggingExecutor) Run(ctx context.Context, name string, args ...string) (string, string, error)
Run implements Executor.
type OSExecutor ¶
type OSExecutor struct{}
OSExecutor runs commands using os/exec.
type Process ¶ added in v0.9.0
type Process struct {
Stdout io.ReadCloser
// contains filtered or unexported fields
}
Process represents a running long-lived command whose stdout can be read incrementally. The caller must call Close to release resources.
func Start ¶ added in v0.9.0
Start starts a command and returns a Process for reading its stdout. The command is killed when ctx is cancelled.