proc

Documentation

Overview

Package proc implements a generic Shell process executor, which allows us to execute arbitrary commands from within the program.

Index

• func LookPath(path string) (string, error)
• func Must[T any](v T, err error) T
• type ExecuteError
  • func (e ExecuteError) Error() string
• type ExecuteOpt
  • func WithMultiWriters(writers ...bytes.Buffer) ExecuteOpt
  • func WithOutputs(paths ...string) ExecuteOpt
  • func WithWriters(writers ...bytes.Buffer) ExecuteOpt
• type Executor
  • func DefaultExecutor() *Executor
  • func NewExecutor(opts ...Opt) (*Executor, error)
  • func (e *Executor) Execute(args []string, opts ...ExecuteOpt) ([]string, error)
• type NotInPathError
  • func (e NotInPathError) Error() string
• type Opt
  • func WithInheritedEnv() Opt

Functions

func LookPath

func LookPath(path string) (string, error)

LookPath is a safer alternative to the direct use of exec.LookPath, which mitigates issues caused by non-nil errors due to the fact that the Go runtime resolved the executable to the current directory instead of a generic location in $PATH

func Must

func Must[T any](v T, err error) T

Must ensures the return values of a function are not errors therefore negating any further checks that have to be made. Most commonly used as a wrapper within new object declarations

Types

type ExecuteError

type ExecuteError struct {
	ExitCode int
	Err      error
}

ExecuteError is an error during the execution of a subprocess

func (ExecuteError) Error

func (e ExecuteError) Error() string

type ExecuteOpt

type ExecuteOpt func(e *Executor)

ExecuteOpt is a runtime option for the Executor's Execute methods

func WithMultiWriters

func WithMultiWriters(writers ...bytes.Buffer) ExecuteOpt

WithMultiWriters configures the Execute function to use a MultiWriter during execution to simultaneously write to both the system's StdOut/Err and to a provided byte-buffer for each of those descriptors

func WithOutputs

func WithOutputs(paths ...string) ExecuteOpt

WithOutputs configures the Execute function to spawn a GoRoutine which writes the standard output of the command to a file on the filesystem

func WithWriters

func WithWriters(writers ...bytes.Buffer) ExecuteOpt

WithWriters configures the Execute function to spawn a GoRoutine which fills a slice of byte-buffers with date from the StdOut and StdErr output respectively.

type Executor

type Executor struct {

	// exec.Cmd is the embedded Go-native Command to execute
	*exec.Cmd
	// contains filtered or unexported fields
}

func DefaultExecutor

func DefaultExecutor() *Executor

DefaultExecutor is the default Executor implementation and the base for latter configurations via ExecutorOpt's

func NewExecutor

func NewExecutor(opts ...Opt) (*Executor, error)

NewExecutor creates a new Executor with the provided configuration options. The method takes in a set of configuration Options which may configure the Executor. These Options allow Execute to do things like write files, byte-buffers and e.g. inherit the host's environment configuration.

func (*Executor) Execute

func (e *Executor) Execute(args []string, opts ...ExecuteOpt) ([]string, error)

Execute executes a system command on the host operating system's shell, however avoids Shell expansions like globs etc. The method takes in a set of arguments and a set of configuration Options which may configure the execution of the method. These Options allow Execute to do things like write files, byte-buffers and e.g. inherit the host's environment configuration.

type NotInPathError

type NotInPathError struct {
	Executable string
}

NotInPathError means we couldn't find the executable somebody was trying to execute within a subprocess, in the system's PATH

func (NotInPathError) Error

func (e NotInPathError) Error() string

type Opt

type Opt func(e *Executor) error

Opt is a configuration option for the initialization of new Executor's

func WithInheritedEnv

func WithInheritedEnv() Opt

WithInheritedEnv configures the Execute function to inherit the current OS environment settings into the command to be executed