shell

Documentation

Index

• func SetSilent(s bool)
• type Result
  • func NewResult(err error, combinedOutput, errorOutput string) Result
  • func (r Result) Code() int
  • func (r Result) Error() error
  • func (r Result) ErrorWith(msg string) error
  • func (r Result) IsCode(code int) bool
  • func (r Result) IsFailure() bool
  • func (r Result) IsSuccess() bool
  • func (r Result) Output() string
  • func (r Result) String() string
  • func (r Result) Unwrap() Result
  • func (r Result) UnwrapWith(msg string, args ...any) Result
• type Shell
  • func New(command string, args ...string) *Shell
  • func (s *Shell) Args() []string
  • func (s *Shell) Cmd() *exec.Cmd
  • func (s *Shell) Command() string
  • func (s *Shell) Dir() string
  • func (s *Shell) Envs() map[string]string
  • func (s *Shell) Run() Result
  • func (s *Shell) Stderr() io.Writer
  • func (s *Shell) Stdin() io.Reader
  • func (s *Shell) Stdout() io.Writer
  • func (s *Shell) Timeout() time.Duration
  • func (s *Shell) WithDir(dir string) *Shell
  • func (s *Shell) WithEnv(key, value string) *Shell
  • func (s *Shell) WithEnvs(envs map[string]string) *Shell
  • func (s *Shell) WithStderr(stderr io.Writer) *Shell
  • func (s *Shell) WithStdin(stdin io.Reader) *Shell
  • func (s *Shell) WithStdout(stdout io.Writer) *Shell
  • func (s *Shell) WithTimeout(timeout time.Duration) *Shell

Functions

func SetSilent

func SetSilent(s bool)

SetSilent toggles the package-level silent flag.

Types

type Result

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

Result holds the outcome of a shell command execution: its combined output, resulting error (if any), and exit code.

func NewResult

func NewResult(err error, combinedOutput, errorOutput string) Result

NewResult builds a Result from a command's execution error, its combined stdout+stderr output, and its stderr-only output. If err is non-nil, it is replaced with an error wrapping errorOutput, and the exit code is extracted from err when it is an *exec.ExitError.

func (Result) Code

func (r Result) Code() int

Code returns the command's exit code.

func (Result) Error

func (r Result) Error() error

Error returns the error produced by the command, or nil on success.

func (Result) ErrorWith

func (r Result) ErrorWith(msg string) error

ErrorWith returns the command's error prefixed with msg, or nil if the command succeeded.

func (Result) IsCode

func (r Result) IsCode(code int) bool

IsCode reports whether the command's exit code matches code.

func (Result) IsFailure

func (r Result) IsFailure() bool

IsFailure reports whether the command completed with an error.

func (Result) IsSuccess

func (r Result) IsSuccess() bool

IsSuccess reports whether the command completed without error.

func (Result) Output

func (r Result) Output() string

Output returns the combined stdout+stderr output of the command.

func (Result) String

func (r Result) String() string

String returns the command's combined output.

func (Result) Unwrap

func (r Result) Unwrap() Result

Unwrap prints the error and exits the process with status 1 if the command failed; otherwise it returns r unchanged.

func (Result) UnwrapWith

func (r Result) UnwrapWith(msg string, args ...any) Result

UnwrapWith behaves like Unwrap, but prints msg (formatted with args) before the error when the command failed.

type Shell

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

Shell describes a command to run, along with its working directory, environment, timeout, and I/O streams.

func New

func New(command string, args ...string) *Shell

New creates a new Shell instance with stdin/stdout/stderr set up to os.Stdin, os.Stdout, and os.Stderr, respectively.

func (*Shell) Args

func (s *Shell) Args() []string

Args returns the arguments passed to the command.

func (*Shell) Cmd

func (s *Shell) Cmd() *exec.Cmd

Cmd creates an exec.Cmd instance based on the Shell configuration.

func (*Shell) Command

func (s *Shell) Command() string

Command returns the command name to execute.

func (*Shell) Dir

func (s *Shell) Dir() string

Dir returns the working directory for the shell command.

func (*Shell) Envs

func (s *Shell) Envs() map[string]string

Envs returns the environment variables set for the shell command.

func (*Shell) Run

func (s *Shell) Run() Result

Run executes the shell command and returns its combined output and any error that occurred during execution. If stdout or stderr is set, it will return an empty string for the output and the error from cmd.Run() instead.

func (*Shell) Stderr

func (s *Shell) Stderr() io.Writer

Stderr returns the standard error configured for the shell command.

func (*Shell) Stdin

func (s *Shell) Stdin() io.Reader

Stdin returns the standard input configured for the shell command.

func (*Shell) Stdout

func (s *Shell) Stdout() io.Writer

Stdout returns the standard output configured for the shell command.

func (*Shell) Timeout

func (s *Shell) Timeout() time.Duration

Timeout returns the timeout configured for the shell command.

func (*Shell) WithDir

func (s *Shell) WithDir(dir string) *Shell

WithDir sets the working directory for the shell command.

func (*Shell) WithEnv

func (s *Shell) WithEnv(key, value string) *Shell

WithEnv sets an environment variable for the shell command.

func (*Shell) WithEnvs

func (s *Shell) WithEnvs(envs map[string]string) *Shell

WithEnvs sets multiple environment variables for the shell command.

func (*Shell) WithStderr

func (s *Shell) WithStderr(stderr io.Writer) *Shell

WithStderr sets the standard error for the shell command.

func (*Shell) WithStdin

func (s *Shell) WithStdin(stdin io.Reader) *Shell

WithStdin sets the standard input for the shell command.

func (*Shell) WithStdout

func (s *Shell) WithStdout(stdout io.Writer) *Shell

WithStdout sets the standard output for the shell command.

func (*Shell) WithTimeout

func (s *Shell) WithTimeout(timeout time.Duration) *Shell

WithTimeout sets a timeout for the shell command. If the command does not complete within the specified duration, it will be killed and an error will be returned.