shell

Documentation

Overview

Package shell provides facilities for executing commands on various targets.

Index

• func JoinEnv(key string, vals []string) string
• func SplitEnv(s string) (key string, vals []string)
• type Cmd
  • func Command(name string, args ...string) Cmd
  • func (cmd Cmd) Call(ctx context.Context) (string, error)
  • func (cmd Cmd) Capture(stdout, stderr io.Writer) Cmd
  • func (cmd Cmd) Env(env *Env) Cmd
  • func (cmd Cmd) Format(f fmt.State, c rune)
  • func (cmd Cmd) In(dir string) Cmd
  • func (cmd Cmd) On(target Target) Cmd
  • func (cmd Cmd) Read(stdin io.Reader) Cmd
  • func (cmd Cmd) Run(ctx context.Context) error
  • func (cmd Cmd) Start(ctx context.Context) (Process, error)
  • func (cmd Cmd) Verbose() Cmd
  • func (cmd Cmd) With(args ...string) Cmd
• type Env
  • func CloneEnv() *Env
  • func NewEnv() *Env
  • func (e *Env) Add(key string)
  • func (e *Env) AddPathEnd(key string, paths ...string) *Env
  • func (e *Env) AddPathStart(key string, paths ...string) *Env
  • func (e *Env) Exists(key string) bool
  • func (e *Env) Get(key string) string
  • func (e *Env) Keys() []string
  • func (e *Env) Set(key, value string) *Env
  • func (e *Env) Unset(key string) *Env
  • func (e *Env) Vars() []string
• type Process
• type Target

Functions

func JoinEnv

func JoinEnv(key string, vals []string) string

JoinEnv combines the given key and values into an environment variable string.

func SplitEnv

func SplitEnv(s string) (key string, vals []string)

SplitEnv splits the given environment variable string into key and values.

Types

type Cmd

type Cmd struct {
	// Name is the name of the command to run
	Name string
	// Args is the arguments handed to the command, it should not include the command itself.
	Args []string
	// Target is the target to execute the command on
	// If left as nil, this will default to LocalTarget.
	Target Target
	// Verbosity makes the command echo it's stdout and stderr to the supplied logging context.
	// It will also log the command itself as it starts.
	Verbosity bool
	// Dir sets the working directory for the command.
	Dir string
	// Stdout is the writer to which the command will write it's standard output if set.
	Stdout io.Writer
	// Stdout is the writer to which the command will write it's standard error if set.
	Stderr io.Writer
	// Stdin is the reader from which the command will read it's standard input if set.
	Stdin io.Reader
	// Environment is the processes environment, if set.
	Environment *Env
}

Cmd holds the configuration to run an external command.

A Cmd can be run any number of times, and new commands may be derived from existing ones.

func Command

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

Command returns a Cmd with the specified command and arguments set.

func (Cmd) Call

func (cmd Cmd) Call(ctx context.Context) (string, error)

Call executes the command, capturing its output. This is a helper for the common case where you want to run a command, capture all its output into a string and see if it succeeded.

func (Cmd) Capture

func (cmd Cmd) Capture(stdout, stderr io.Writer) Cmd

Capture returns a copy of the Cmd with Stdout and Stderr set.

func (Cmd) Env

func (cmd Cmd) Env(env *Env) Cmd

Env returns a copy of the Cmd with the Environment set to env.

func (Cmd) Format

func (cmd Cmd) Format(f fmt.State, c rune)

func (Cmd) In

func (cmd Cmd) In(dir string) Cmd

In returns a copy of the Cmd with the Dir set to dir.

func (Cmd) On

func (cmd Cmd) On(target Target) Cmd

On returns a copy of the Cmd with the Target set to target.

func (Cmd) Read

func (cmd Cmd) Read(stdin io.Reader) Cmd

Read returns a copy of the Cmd with Stdin set.

func (Cmd) Run

func (cmd Cmd) Run(ctx context.Context) error

Run executes the command, and blocks until it completes or the context is cancelled.

func (Cmd) Start

func (cmd Cmd) Start(ctx context.Context) (Process, error)

Start executes the command and returns immediately.

func (Cmd) Verbose

func (cmd Cmd) Verbose() Cmd

Verbose returns a copy of the Cmd with the Verbosity flag set to true.

func (Cmd) With

func (cmd Cmd) With(args ...string) Cmd

With returns a copy of the Cmd with the args added to the end of Args.

type Env

type Env struct {
	PathListSeparator rune
	// contains filtered or unexported fields
}

Env holds the environment variables for a new process.

func CloneEnv

func CloneEnv() *Env

CloneEnv returns a copy of the current process's environment variables.

func NewEnv

func NewEnv() *Env

NewEnv returns a copy of the current process's environment variables.

func (*Env) Add

func (e *Env) Add(key string)

Add inserts a new environment variable that is of the form "key=value". That is, it parses the environment variable if necessary

func (*Env) AddPathEnd

func (e *Env) AddPathEnd(key string, paths ...string) *Env

AddPathEnd adds paths to the start of the environment variable with the specified key, using the os.PathListSeparator as a delimiter. If there was no existing environment variable with the given key then it is created.

func (*Env) AddPathStart

func (e *Env) AddPathStart(key string, paths ...string) *Env

AddPathStart adds paths to the start of the environment variable with the specified key, using e.PathListSeparator as a delimiter. If there was no existing environment variable with the given key then it is created.

func (*Env) Exists

func (e *Env) Exists(key string) bool

Exists returns true if the environment variable with the specified key exists. The variable can be of the form 'key=value' or simply 'key'.

func (*Env) Get

func (e *Env) Get(key string) string

Get returns the value of an environment variable stored in the form 'key=value'. If there are no variables with the key, then an empty string is returned.

func (*Env) Keys

func (e *Env) Keys() []string

Keys returns all of the environment variable keys.

func (*Env) Set

func (e *Env) Set(key, value string) *Env

Set adds or replaces an environment variable in the form 'key=value' or 'key'.

func (*Env) Unset

func (e *Env) Unset(key string) *Env

Unset removes an environment variable in the form 'key=value' or 'key'.

func (*Env) Vars

func (e *Env) Vars() []string

Vars returns a copy of the full list of environment variables.

type Process

type Process interface {
	// Kill is called to ask the process to stop immediately.
	// It must be safe to call Kill more than once, and on a non running process.
	Kill() error
	// Wait blocks until the process has completed or the context is cancelled,
	// returning an error if the process failed for some reason.
	Wait(ctx context.Context) error
}

Process is the interface to a running process, as started by a Target.

type Target

type Target interface {
	// Start is invoked to execute the supplied command.
	// It must return either a Process object that can be used to control the command, or an error.
	Start(cmd Cmd) (Process, error)
}

Target is the interface for an object that supports execution of Commands.

var (
	// LocalTarget is an implementation of Target that runs the command on the local machine using the exec package.
	LocalTarget Target = localTarget{}
)