gosh

package module
v0.0.0-...-af53111 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 11, 2016 License: Apache-2.0 Imports: 13 Imported by: 7

README

gosh Build Status Doc Status


A simple-minded API for exec'ing in Go.

Avoid all the futz with connecting your inputstreams to your outputstreams. Get error handling by default instead of return codes (you forgot to check them, admit it). Skip over miles of boilerplate. Generally be a happier person.

Example:

// basic commands
Sh("head")("--bytes=20", "/dev/zero")()

// making your own shorthand
aptget := Sh("apt-get")("install")
aptyes := aptget("-y")
// now `aptyes("git")` will install git
// the `-y` argument is baked in so apt will proceed automatically

Gosh is meant to be usable as a bash or python replacement in rapid-iteration scripting, as well as heavy duty usage as a library in large applications.

Gosh discovers applications on your system using the $PATH mechanism so comfortable and familiar from your usual shell.

Any kind of collection can be used for input and output of strings and bytes -- buffers, strings, channels, readers, writers -- you name it, it'll fly. Simple applications set up their input and output, call the command, wait for return, and go about their business. Fancier applications that want to streaming parallel processing can drop in a channel and parallel the day away. Shell-like scripts get standard input and output wired up automatically without boilerplate.

After every call, a new command object is returned. (Each command object is immutable.) So, a series of similar commands can be templated and reused!

Error handling is to panic by default if a command has a non-zero exit code. This is like running bash with with set -e (stop on errors -- i.e., what you should literally always be doing). If you need to handle other exit codes, you can provide a list of okay codes.

No external dependencies.

Inspired by https://github.com/amoffat/sh/ and https://github.com/polydawn/josh/ .

No warranty implied. Do not place in closed boxes with cats. May eat your homework. Is probably web scale (but no one knows what that means). Artisanally crafted with venom and scorn. Coroutines included.

Building

./goad

Documentation

Index

Constants

This section is empty.

Variables

View Source
var AnyExit []int = make([]int, 256)

Bake this in to make `Run()` accept any exit code.

View Source
var DefaultIO = Opts{
	In:  os.Stdin,
	Out: os.Stdout,
	Err: os.Stderr,
}

Bake this in to connect all the std in/out/err streams to the parent process.

This resembles the usual behavior of your interactive shell (but is probably not what you want if using gosh in the middle of a large application).

View Source
var NullIO = Opts{
	In:  bytes.Buffer{},
	Out: ioutil.Discard,
	Err: ioutil.Discard,
}

Bake this in to silence all output and error messages and disconnect the input stream.

Functions

This section is empty.

Types

type ClearEnv

type ClearEnv struct{}

type Command

type Command func(args ...interface{}) Proc

Calling a `Command` merges in the arguments and then immediately launches a `Proc`. The `Command()` call waits for the `Proc` to complete, panics if it fails, and finally returns the `Proc`.

The parameters can take many forms:

  • `string` or `[]string` types will be merged into the command args list.
  • `Env` types will be joined with the command environment variables.
  • `ClearEnv` will discard *all* current environment variables.
  • `Opts` objects can do all of the above, and also set the working directory, set the input and output streams, configure the "acceptable" exit codes, and even inject a custom Proc Launcher.

Use `Command.Start()` to just launch and immediately return the `Proc` if you want to do your own job control.

func Gosh

func Gosh(args ...interface{}) Command

Creates a new Command with the defaults for shell-like behavior.

func (Command) Bake

func (c Command) Bake(args ...interface{}) Command

Using `Bake` on a `Command` merges in the arguments, keeping them as a template that applies to every Proc launched from the new `Command` that's returned.

The returned command can launch `Proc`s repeatedly or futher baked, just like the original.

All the same types that `Command()` can accept, `Bake()` can accept too. They have the same effects.

The returned command is a "deep copy" for everything except the In/Out/Err readers/writers -- it's completely separated; further changes do not have the power to mutate the original. (Except when the In/Out/Err references are themselves stateful; we have no way to deepcopy on those without knowing what their implementations are).

func (Command) CombinedOutput

func (c Command) CombinedOutput() string

Same as `Output()`, but acts on both stdout and stderr.

func (Command) Output

func (c Command) Output() string

Starts execution of the command, waits until completion, and then returns the accumulated output of the command as a string. As with `Run()`, a panic will be emitted if the command does not execute successfully.

This does not include output from stderr; use `CombinedOutput()` for that.

This is shorthand equivalent to `Bake(Opts{Out:val}).Run()`; that is, it will overrule any previously configured output, and also it has no effect on where stderr will go.

func (Command) Run

func (c Command) Run() Proc

Starts execution of the command, and waits until completion before returning. If the command does not execute successfully, a panic of type FailureExitCode will be emitted; use `Opts.OkExit` to configure what is considered success.

The is exactly the behavior of a no-arg invokation on an Command, i.e.

`Gosh("echo")()`

and

`Gosh("echo").Run()`

are interchangable and behave identically.

The behavior of an invoking Command with parameters is the same as baking in the extra parameters and then calling Run:

`Gosh("echo")("my", "story")`

and

`Gosh("echo", "my", "story").Run()`

and

`Gosh("echo").Bake("my", "story").Run()`

are all interchangable and behave identically.

Use the `Start()` method instead if you need to run a task in the background, or otherwise need greater control over execution.

func (Command) RunAndReport

func (c Command) RunAndReport() Proc

Like `Run()`, but overrides stdout and stderr to be collected and reported along with the error that is raised if the process ends with a non-zero exit status.

The conmingled stdout+stderr will be in the `FailureExitCode.Message` field.

This is often a useful helper method for the behavior an application wants from a non-interactive background task (e.g. "untar; if it succeeds, I already understand what that means; tell me the output if and only if it fails").

Note that this implies that stdout and stderr of the process will be buffered by gosh in memory. If your process may produce large amounts of output, this helper method may not be appropriate for your use case.

func (Command) Start

func (c Command) Start() Proc

Starts execution of the command, and immediately returns a `Proc` that can be used to track execution of the command, configure exit listeners, etc.

type Env

type Env map[string]string

func (Env) Merge

func (x Env) Merge(y Env) Env

func (Env) ToSlice

func (x Env) ToSlice() []string

type Error

type Error interface {
	error
	GoshError() // marker method
}

`gosh.Error` is a grouping interface for all errors raised by gosh.

Errors fall into two main headings...

Configuration errors:

  • IncomprehensibleCommandModifierError
  • NoArgumentsError

Execution errors:

  • NoSuchCommandError
  • ProcMonitorError
  • FailureExitCode

Gosh typically raises errors with panics. This is a deliberate design choice to make the easiest, tersest usages of gosh feel as much as possible like writing a shell script with "-e" mode (exit immediately on error) set.

All gosh errors can be distingushed by use of type switches. (Gosh does not use "value" type errors (i.e. `var SomeError = fmt.Errorf[...]`) because these are ineffective at holding information for programatic use later.)

Gosh errors may contain special fields with additional information -- one near-ubiquitous example being the "cause" error -- which are always exported, so that you can access them after casting the error to its specific type. At no point should your application ever be required to parse strings in order to handle gosh errors.

(Note: The authors of gosh recommend checking out a hierarchical error system, like the one provided by `github.com/spacemonkeygo/errors`, but we have not used it here in the interest of keeping gosh's dependencies standard-library-only.)

type ExecProc

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

`gosh.Proc` implementation using `os/exec`.

func (*ExecProc) AddExitListener

func (p *ExecProc) AddExitListener(callback func(Proc))

func (*ExecProc) GetExitCode

func (p *ExecProc) GetExitCode() int

func (*ExecProc) GetExitCodeSoon

func (p *ExecProc) GetExitCodeSoon(d time.Duration) int

func (*ExecProc) Kill

func (p *ExecProc) Kill()

func (*ExecProc) Pid

func (p *ExecProc) Pid() int

func (*ExecProc) Signal

func (p *ExecProc) Signal(sig os.Signal)

func (*ExecProc) State

func (p *ExecProc) State() State

func (*ExecProc) Wait

func (p *ExecProc) Wait()

func (*ExecProc) WaitChan

func (p *ExecProc) WaitChan() <-chan struct{}

func (*ExecProc) WaitSoon

func (p *ExecProc) WaitSoon(d time.Duration) bool

type FailureExitCode

type FailureExitCode struct {
	Cmdname string
	Code    int
	Message string
}

Error for commands run by Sh that exited with a non-successful status.

What exactly qualifies as an unsuccessful status can be defined per command, but by default is any exit code other than zero.

func (FailureExitCode) Error

func (err FailureExitCode) Error() string

func (FailureExitCode) GoshError

func (err FailureExitCode) GoshError()

type IncomprehensibleCommandModifierError

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

Error when any of the command templating functions is called with arguments of an unexpected type. The `interface{}` arguments to command templating functions may only be of the following types:

  • Opts
  • Env
  • ClearEnv
  • string
  • []string

This should mostly be a compile-time problem as long as you write your script to not actually pass unchecked types of interface{}.

func (IncomprehensibleCommandModifierError) Error

func (IncomprehensibleCommandModifierError) GoshError

func (err IncomprehensibleCommandModifierError) GoshError()

type Launcher

type Launcher func(Opts) Proc

func ExecCustomizingLauncher

func ExecCustomizingLauncher(trailingHook func(*exec.Cmd)) Launcher

Launches a process via stdlib `exec`, and gives the provided hook function a shot at running against the `exec.Cmd` to do any last-minute preparations -- this is useful if you need to set exotic attributes like `SysProcAttr` which are not normally exposed by Gosh's shellish layer.

type NoArgumentsError

type NoArgumentsError struct{}

NoArgumentsErr is raised when a command template is launched but has no arguments.

func (NoArgumentsError) Error

func (err NoArgumentsError) Error() string

func (NoArgumentsError) GoshError

func (err NoArgumentsError) GoshError()

type NoSuchCommandError

type NoSuchCommandError struct {
	Name  string
	Cause error
}

NoSuchCommandError is raised when a command name (the first argument) cannot be found.

func (NoSuchCommandError) Error

func (err NoSuchCommandError) Error() string

func (NoSuchCommandError) GoshError

func (err NoSuchCommandError) GoshError()

type NoSuchCwdError

type NoSuchCwdError struct {
	Path  string // attempted cwd path
	Cause error  // is an `*os.PathError`; may clarify whether not a dir or perm denied
}

NoSuchCwdError is raised when a command template is launched but has no arguments.

func (NoSuchCwdError) Error

func (err NoSuchCwdError) Error() string

func (NoSuchCwdError) GoshError

func (err NoSuchCwdError) GoshError()

type Opts

type Opts struct {
	Args []string

	Env Env

	Cwd string

	/*
		Can be a:
		  - string, in which case it will be copied in literally
		  - []byte, again, taken literally
		  - io.Reader, which will be streamed in
		  - bytes.Buffer, all that sort of thing, taken literally
		  - <-chan string, in which case that will be streamed in
		  - <-chan byte[], in which case that will be streamed in
		  - another Command, in which case that will be started with this one and its output piped into this one
	*/
	In interface{}

	/*
		Can be a:
		  - bytes.Buffer, which will be written to literally
		  - io.Writer, which will be written to streamingly, flushed to whenever the command flushes
		  - chan<- string, which will be written to streamingly, flushed to whenever a line break occurs in the output
		  - chan<- byte[], which will be written to streamingly, flushed to whenever the command flushes

		(There's nothing that's quite the equivalent of how you can give In a string, sadly; since
		strings are immutable in golang, you can't set Out=&str and get anywhere.)
	*/
	Out interface{}

	/*
		Can be all the same things Out can be, and does the same thing, but for stderr.
	*/
	Err interface{}

	/*
		Exit status codes that are to be considered "successful".  If not provided, [0] is the default.
		(If this slice is provided, zero will -not- be considered a success code unless explicitly included.)
	*/
	OkExit []int

	/*
		The `Launcher` to use when spawning a process from this template.

		You can replace this with your own function in order to do last minute
		tweaks or logging!
	*/
	Launcher Launcher
}

func (Opts) Merge

func (x Opts) Merge(y Opts) Opts

Apply 'y' to 'x', returning a new structure. 'y' trumps.

type Proc

type Proc interface {
	State() State

	/*
		Returns the pid of the process, or -1 if it isn't started yet.

		If an implementation doesn't have a concept of 'pid', it should return 0.
	*/
	Pid() int

	/*
		Returns a channel that will be open until the command is complete.
		This is suitable for use in a select block.
	*/
	WaitChan() <-chan struct{}

	/*
		Waits for the command to exit before returning.

		There are no consequences to waiting on a single command repeatedly;
		all wait calls will return normally when the command completes.  The order
		in which multiple wait calls will return is undefined.  Similarly, there
		are no consequences to waiting on a command that has not yet started;
		the function will still wait without error until the command finishes.
		(Much friendlier than os.exec.Cmd.Wait(), neh?)
	*/
	Wait()

	/*
		Waits for the command to exit before returning, or for the specified duration.
		Returns true if the return was due to the command finishing, or false if the
		return was due to timeout.
	*/
	WaitSoon(d time.Duration) bool

	/*
		Waits for the command to exit if it has not already, then returns the exit code.
	*/
	GetExitCode() int

	/*
		Waits for the command to exit if it has not already, or for the specified duration,
		then either returns the exit code, or -1 if the duration expired and the command
		still hasn't returned.
	*/
	GetExitCodeSoon(d time.Duration) int

	/*
		Add a function to be called when this process completes.

		These listener functions will be invoked after the exit code and other command
		state is final, but before other `Wait()` methods unblock.
		(This means if you want for example to log a message that a process exited, and
		your main function is going to exit immediately after it's finished
		Wait()'ing for that process... if you use AddExitListener()
		to invoke your log function then you will always get the log.)

		The listener function should complete quickly and not try to perform other blocking
		operations or locks, since other actions are waiting until the listeners have all
		been called.

		Panics that escape the function may result in undefined behavior, and failure
		to call other listeners; do not panic in a listener.
		Consider sending any errors to a (buffered!!) channel instead.

		If the command is already in the state FINISHED or PANICKED, the callback function
		will be invoked immediately in the current goroutine.
	*/
	AddExitListener(callback func(Proc))

	Kill()

	Signal(os.Signal)
}

Proc observes and manipulates a running command.

It is similar to `exec.Cmd`, but applied to an in-flight process (setup is performed by a separate interface). Unlike contracts of `exec.Cmd`, all functions on Proc are safe to call repeatedly, and in any order.

func ExecLauncher

func ExecLauncher(cmdt Opts) Proc

Launches a process via stdlib `exec`.

func ExecProcCmd

func ExecProcCmd(cmd *exec.Cmd) Proc

func Sh

func Sh(args ...interface{}) Proc

Creates a new Command and immediately invokes it, returning when the process is complete.

This is shorthand for `Gosh(args).Run()`.

type ProcMonitorError

type ProcMonitorError struct {
	Cause error
}

ProcMonitorError is raised to report any errors encountered while trying to wait for completion, shuttle I/O, or get information about the exit status of a command.

When a ProcMonitorError occurs, the Proc `Status()` will also become `PANICKED`, and gosh may no longer be able to reliably detect the state of the command.

func (ProcMonitorError) Error

func (err ProcMonitorError) Error() string

func (ProcMonitorError) GoshError

func (err ProcMonitorError) GoshError()

type State

type State int32
const (
	/*
		'Unstarted' is the state of a command that has been constructed, but execution has not yet begun.
	*/
	UNSTARTED State = iota

	/*
		'Running' is the state of a command that has begun execution, but not yet finished.
	*/
	RUNNING

	/*
		'Finished' is the state of a command that has finished normally.

		The exit code may or may not have been success, but at the very least we
		successfully observed that exit code.
	*/
	FINISHED

	/*
		'Panicked' is the state of a command that at some point began execution, but has encountered
		serious problems.

		It may not be clear whether or not the command is still running, since a panic implies we no
		longer have completely clear visibility to the command on the underlying system.  The exit
		code may not be reliably known.
	*/
	PANICKED
)

func (State) IsDone

func (state State) IsDone() bool

Returns true if the command is finished (either gracefully, or with internal errors).

func (State) IsFinishedGracefully

func (state State) IsFinishedGracefully() bool

Returns true if the command is finished gracefully. (A nonzero exit code may still be set.)

func (State) IsRunning

func (state State) IsRunning() bool

Returns true if the command is current running.

func (State) IsStarted

func (state State) IsStarted() bool

Returns true if the command has ever been started (including if the command is already finished).

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL