Documentation
¶
Index ¶
- Variables
- type ClearEnv
- type Command
- type Env
- type Error
- type ExecProc
- func (p *ExecProc) AddExitListener(callback func(Proc))
- func (p *ExecProc) GetExitCode() int
- func (p *ExecProc) GetExitCodeSoon(d time.Duration) int
- func (p *ExecProc) Kill()
- func (p *ExecProc) Pid() int
- func (p *ExecProc) Signal(sig os.Signal)
- func (p *ExecProc) State() State
- func (p *ExecProc) Wait()
- func (p *ExecProc) WaitChan() <-chan struct{}
- func (p *ExecProc) WaitSoon(d time.Duration) bool
- type FailureExitCode
- type IncomprehensibleCommandModifierError
- type Launcher
- type NoArgumentsError
- type NoSuchCommandError
- type NoSuchCwdError
- type Opts
- type Proc
- type ProcMonitorError
- type State
Constants ¶
This section is empty.
Variables ¶
var AnyExit []int = make([]int, 256)
Bake this in to make `Run()` accept any exit code.
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).
Bake this in to silence all output and error messages and disconnect the input stream.
Functions ¶
This section is empty.
Types ¶
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 ¶
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 ¶
Same as `Output()`, but acts on both stdout and stderr.
func (Command) Output ¶
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 ¶
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 ¶
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.
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 (*ExecProc) GetExitCode ¶
type FailureExitCode ¶
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 (err IncomprehensibleCommandModifierError) Error() string
func (IncomprehensibleCommandModifierError) GoshError ¶
func (err IncomprehensibleCommandModifierError) GoshError()
type Launcher ¶
func ExecCustomizingLauncher ¶
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 ¶
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
}
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 ExecProcCmd ¶
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 ¶
Returns true if the command is finished (either gracefully, or with internal errors).
func (State) IsFinishedGracefully ¶
Returns true if the command is finished gracefully. (A nonzero exit code may still be set.)
