exec

Documentation

Overview

Package exec is a replacement for os/exec and provides a Cmd struct that wraps os/exec.Cmd with additional builder design pattern methods and an option to kill sub processes.

Index

• type Cmd
  • func Command(name string, args ...string) *Cmd
  • func (c *Cmd) Run(ctx context.Context) (*Result, error)
  • func (c *Cmd) String() string
  • func (c *Cmd) WithDir(dir string) *Cmd
  • func (c *Cmd) WithEnv(env []string) *Cmd
  • func (c *Cmd) WithEnvVar(key, value string) *Cmd
  • func (c *Cmd) WithKillSubProcesses() *Cmd
  • func (c *Cmd) WithStdin(stdin io.Reader) *Cmd
• type Result
  • func (r *Result) CheckExitCode(validExitCodes ...int) error

Types

type Cmd

type Cmd struct {
	// contains filtered or unexported fields
}

func Command

func Command(name string, args ...string) *Cmd

Command returns the Cmd struct to execute the named program with the given arguments.

If name contains no path separators, Command uses LookPath to resolve name to a complete path if possible. Otherwise it uses name directly as Path.

The returned Cmd's arguments are constructed from the command name followed by the elements of arg, so arg should not include the command name itself. For example, Command("echo", "hello").

func (*Cmd) Run

func (c *Cmd) Run(ctx context.Context) (*Result, error)

Run the command and wait for the process to exit or the context to be canceled. Non zero exit codes are not cosidered errors. Context errors will be returned in wrapped form.

func (*Cmd) String

func (c *Cmd) String() string

String returns a string representation of the command which might not exactly be identical to the real command line that would be exected.

func (*Cmd) WithDir

func (c *Cmd) WithDir(dir string) *Cmd

WithDir specifies the working directory of the command. If dir is the empty string, Run runs the command in the calling process's current directory.

func (*Cmd) WithEnv

func (c *Cmd) WithEnv(env []string) *Cmd

WithEnv specifies the environment of the process. Each entry is of the form "key=value". If env is nil, the new process uses the current process's environment. If env contains duplicate environment keys, only the last value in the slice for each duplicate key is used. As a special case on Windows, SYSTEMROOT is always added if missing and not explicitly set to the empty string.

func (*Cmd) WithEnvVar

func (c *Cmd) WithEnvVar(key, value string) *Cmd

WithEnvVar inherits the current process's environment and adds another variable named key with the passed value.

func (*Cmd) WithKillSubProcesses

func (c *Cmd) WithKillSubProcesses() *Cmd

func (*Cmd) WithStdin

func (c *Cmd) WithStdin(stdin io.Reader) *Cmd

WithStdin specifies the process's standard input.

If stdin is nil, the process reads from the null device (os.DevNull).

If stdin is an *os.File, the process's standard input is connected directly to that file.

Otherwise, during the execution of the command a separate goroutine reads from stdin and delivers that data to the command over a pipe. In this case, Wait does not complete until the goroutine stops copying, either because it has reached the end of stdin (EOF or a read error) or because writing to the pipe returned an error.

type Result

type Result struct {
	ExitCode  int
	ExitState string
	Output    string
	Stdout    string
	Stderr    string
}

func (*Result) CheckExitCode

func (r *Result) CheckExitCode(validExitCodes ...int) error

CheckExitCode returns the ExitState as error if the ExitCode is not one of the passed validExitCodes or non zero if no validExitCodes are passed.