Documentation
¶
Overview ¶
Package executil contains utilities for running OS commands.
TODO(a.garipov): Consider adding metrics and telemetry.
Index ¶
- func ExitCodeFromError(err error) (c osutil.ExitCode, ok bool)
- func Run(ctx context.Context, cons CommandConstructor, conf *CommandConfig) (err error)
- func RunWithPeek(ctx context.Context, cons CommandConstructor, errLimit datasize.ByteSize, ...) (err error)
- type Command
- type CommandConfig
- type CommandConstructor
- type EmptyCommand
- type EmptyCommandConstructor
- type ExitCodeError
- type SystemCommand
- type SystemCommandConstructor
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExitCodeFromError ¶
ExitCodeFromError returns an exit code and true if err contains an ExitCodeError. Otherwise, it returns 0 and false.
Example ¶
cons := executil.SystemCommandConstructor{}
ctx := context.Background()
err := executil.Run(ctx, cons, &executil.CommandConfig{
Path: shell,
Args: []string{"-c", "exit 123"},
})
fmt.Println(err)
fmt.Println(executil.ExitCodeFromError(err))
Output: running: exit status 123 123 true
func Run ¶
func Run(ctx context.Context, cons CommandConstructor, conf *CommandConfig) (err error)
Run is a utility function that constructs a command, starts it, and waits for it to complete. cons must not be nil. conf must not be nil and must be valid.
func RunWithPeek ¶
func RunWithPeek( ctx context.Context, cons CommandConstructor, errLimit datasize.ByteSize, cmdPath string, args ...string, ) (err error)
RunWithPeek is a utility function that constructs a command, starts it, and waits for it to complete. If there is any error, it is wrapped with the first errLimit bytes of stderr and stdout. cmdPath should not be empty.
Example ¶
cons := executil.SystemCommandConstructor{}
ctx := context.Background()
okCmd := `exit 0`
errCmd := `printf 'a long error!\n' 1>&2 && exit 1`
if runtime.GOOS == "windows" {
errCmd = `$host.ui.WriteErrorLine('a long error!') ; exit 1`
}
const limit = 8 * datasize.B
err := executil.RunWithPeek(ctx, cons, limit, shell, "-c", okCmd)
fmt.Println(err)
err = executil.RunWithPeek(ctx, cons, limit, shell, "-c", errCmd)
fmt.Println(err)
Output: <nil> running: exit status 1; stderr peek: "a long e"; stdout peek: ""
Types ¶
type Command ¶
type Command interface {
// Cancel must stop the process and make all Wait calls exit. It must not
// be called before the call to Start.
//
// Implementations must document if they're using the provided context for
// cancellation or not.
Cancel(ctx context.Context) (err error)
// Start must start the execution of the command but not wait for it to
// complete. Start must only be called once. After a successful call to
// Start, Cancel or Wait must be called.
//
// Implementations must document if they're using the provided context for
// cancellation or not.
Start(ctx context.Context) (err error)
// Wait waits for the command to exit. Wait must only be called after
// Start.
//
// Implementations must document if they're using the provided context for
// cancellation or not.
Wait(ctx context.Context) (err error)
}
Command is the interface for OS commands.
Methods must return an error containing an ExitCodeError if the error signals that the process has exited with a non-zero exit code.
type CommandConfig ¶
type CommandConfig struct {
// Stderr, if not nil, is the process's standard error.
//
// See [exec.Cmd.Stderr].
Stderr io.Writer
// Stdin, if not nil, is the process's standard input.
//
// See [exec.Cmd.Stdin].
Stdin io.Reader
// Stdout, if not nil, is the process's standard output.
//
// See [exec.Cmd.Stdout].
Stdout io.Writer
// Path is the path to the command to run. It should not be empty.
Path string
// Args, if not empty, are the command-line arguments, excluding the command
// name itself.
Args []string
}
CommandConfig is the configuration for a command to run.
type CommandConstructor ¶
type CommandConstructor interface {
// New creates an OS command ready to run. conf should not be nil and
// should be valid. If err is not nil, c must be nil, and vice versa.
// Implementations must document if they're using the provided context for
// cancellation.
New(ctx context.Context, conf *CommandConfig) (c Command, err error)
}
CommandConstructor is the interface for creating OS commands.
type EmptyCommand ¶
type EmptyCommand struct{}
EmptyCommand is a Command that does nothing. Its methods ignore the context and the returned errors are always nil.
func (EmptyCommand) Cancel ¶
func (EmptyCommand) Cancel(_ context.Context) (err error)
Cancel implements the Command interface for EmptyCommand.
type EmptyCommandConstructor ¶
type EmptyCommandConstructor struct{}
EmptyCommandConstructor is a CommandConstructor that creates instances of EmptyCommand.
func (EmptyCommandConstructor) New ¶
func (EmptyCommandConstructor) New(_ context.Context, _ *CommandConfig) (c Command, err error)
New implements the CommandConstructor interface for EmptyCommandConstructor. c is always of type EmptyCommand and err is always nil.
type ExitCodeError ¶
type ExitCodeError interface {
error
// ExitCode must return the exit code of the exited process, or -1 if the
// process hasn't exited or was terminated by a signal.
//
// See [os.ProcessState.ExitCode].
ExitCode() (c osutil.ExitCode)
}
ExitCodeError is the interface for errors returned by methods of Command that have an associated exit code.
type SystemCommand ¶
type SystemCommand struct {
// contains filtered or unexported fields
}
SystemCommand is a Command that uses exec.Cmd to execute system commands.
TODO(a.garipov): Consider actually using the context in the methods for cancellation.
func (*SystemCommand) Cancel ¶
func (c *SystemCommand) Cancel(_ context.Context) (err error)
Cancel implements the Command interface for *SystemCommand. The context is not used for cancellation.
type SystemCommandConstructor ¶
type SystemCommandConstructor struct{}
SystemCommandConstructor is a CommandConstructor that creates instances of SystemCommand.
func (SystemCommandConstructor) New ¶
func (SystemCommandConstructor) New( ctx context.Context, conf *CommandConfig, ) (c Command, err error)
New implements the CommandConstructor interface for SystemCommandConstructor.
See exec.CommandContext for the documentation about the handling of ctx.
Source Files