Documentation
¶
Overview ¶
Package run is a package with utilities for running command and handling results.
Index ¶
Constants ¶
const ( // OutputStdout is the output enum for stdout output. The process' stderr is // still piped and buffered and is used in case of error (reported in the // returned error). OutputStdout OutputType = iota // OutputStderr is the output enum for stderr output. The process' stdout is // never piped and buffered. OutputStderr // OutputCombined is the output enum for stdout+stderr combined output. OutputCombined // OutputNone is the output enum for no output/quiet. The process' stderr is // still piped and buffered and is used in case of error (reported in the // returned error). OutputNone // OutputStream is the output enum for streaming output. OutputStream // ExecModeSync is the execution mode enum for sync processes(blocking). ExecModeSync ExecMode = iota // ExecModeAsync is the execution mode enum for async processes(non blocking). ExecModeAsync // ExecModeDetach is the execution mode enum for detached processes. The // operation is async as [ExecModeAsync] but it has the process group re-set // - the process will survive the callers process exit. ExecModeDetach )
Variables ¶
var ( // ErrCommandTemplate is the error returned when a CommandSpec's Command // template is boggus. ErrCommandTemplate = errors.New("invalid command format template") // ErrTemplateError is the error returned when a CommandSpec's Error template // is boggus. ErrTemplateError = errors.New("invalid error format template") )
Functions ¶
Types ¶
type CommandSet ¶
type CommandSet []CommandSpec
CommandSet is set of commands to be executed together, IOW a command batch.
func (CommandSet) WithContext ¶
func (s CommandSet) WithContext(ctx context.Context, data any) error
WithContext runs all the commands in a CommandSet, no command output is handled. All commands are run as a batch.
type CommandSpec ¶
type CommandSpec struct {
// Command is the command template i.e: "echo '{{.MyDataString}}'".
Command string
// Error is the error template, if the command fails this template is
// used to build the error message, i.e: "failed to parse file {{.FileName}}".
Error string
}
CommandSpec defines a Command template and an Error template. The data structure to be used with the templates is up to the user to define.
func (CommandSpec) WithContext ¶
func (c CommandSpec) WithContext(ctx context.Context, data any) error
WithContext runs a CommandSpec command, no command output is handled.
type ExecMode ¶
type ExecMode int
ExecMode represents the command execution mode: i.e. blocking, non-blocking, detaching etc.
type Options ¶
type Options struct {
// OutputType is the output type requested/configured, it could be either:
// stdout, stderr, combined or none.
OutputType OutputType
// Name is the command name.
Name string
// Args is the command arguments.
Args []string
// Input is written to the process stdin.
Input string
// Timeout is the timeout of the command. If it's not set (or set to 0) no
// timeout will be set/assumed.
Timeout time.Duration
// ExecMode defines the process/command execution mode, i.e. blocking,
// non-blocking, detaching etc.
ExecMode ExecMode
// Dir specifies the working directory of the command/process. If not
// specified the exec.Command's Dir behavior is honored.
Dir string
}
Options represents the command options.
type Result ¶
type Result struct {
// OutputType is the output type requested/configured with [Options].
OutputType OutputType
// Output is the output of the command, depending on the OutputType it could
// be either, stdout, stderr, combined or none.
Output string
// OutputScanners is the scanner for the output of the command. This is set
// only if the [Options] OutputType is OutputStream.
OutputScanners *StreamOutput
// Pid is the PID of the process that started the command. It's only set if
// the [Options]` ExecMode is either ExecModeAsync or ExecModeDetack.
Pid int
}
Result represents the result of running commands.
type Runner ¶
type Runner struct{}
Runner implements the RunnerInterface and represents the runner running commands.
type RunnerInterface ¶
RunnerInterface defines the runner running commands.
var ( // Client is the Runner running commands. Client RunnerInterface )
type StreamOutput ¶
type StreamOutput struct {
// StdOut is the channel for stdout of a command.
StdOut <-chan string
// StdErr is the channel for stderr of a command.
StdErr <-chan string
// Result is the final output of a command. It is same as what cmd.Wait()
// finally returns.
Result <-chan error
}
StreamOutput represents the output channels streaming command result. Executor takes care of closing all channels after all writes are completed. Caller must not try to close channel and should only read from these receive only channels.
type TimeoutError ¶
type TimeoutError struct {
// contains filtered or unexported fields
}
TimeoutError is the error type returned when a command execution times out.
func AsTimeoutError ¶
func AsTimeoutError(err error) (*TimeoutError, bool)
AsTimeoutError returns a TimeoutError if the error is a TimeoutError.
Source Files