Documentation
¶
Overview ¶
Package exc provides a thin, ergonomic wrapper around the standard library's 'os/exec' package.
Index ¶
- type Command
- func (cmd *Command) Clone() *Command
- func (cmd *Command) Exec(ctx context.Context) (io.Reader, error)
- func (cmd *Command) Format(f fmt.State, verb rune)
- func (cmd *Command) HasLabel(label string) bool
- func (cmd *Command) ResentEnv() *Command
- func (cmd *Command) ResetArgs() *Command
- func (cmd *Command) ResetIO() *Command
- func (cmd *Command) ResetLabels() *Command
- func (cmd *Command) ResetStdError() *Command
- func (cmd *Command) ResetStdInput() *Command
- func (cmd *Command) ResetStdOutput() *Command
- func (cmd *Command) Resolve(ctx context.Context) *exec.Cmd
- func (cmd *Command) Run(ctx context.Context) error
- func (cmd *Command) SSH(host string, args ...string) *Command
- func (cmd *Command) SetArgs(a []string) *Command
- func (cmd *Command) SetEnvVar(k, v string) *Command
- func (cmd *Command) Shell(shell string, block string) *Command
- func (cmd *Command) Start(ctx context.Context) fnx.Worker
- func (cmd *Command) UnsetEnvVar(k string) *Command
- func (cmd *Command) WithArgs(a ...string) *Command
- func (cmd *Command) WithDirectory(d string) *Command
- func (cmd *Command) WithID(id string) *Command
- func (cmd *Command) WithLabel(label string) *Command
- func (cmd *Command) WithName(n string) *Command
- func (cmd *Command) WithStdError(w io.Writer) *Command
- func (cmd *Command) WithStdInput(r io.Reader) *Command
- func (cmd *Command) WithStdOutput(w io.Writer) *Command
- func (cmd *Command) Worker() fnx.Worker
- type Error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
ID string
Labels dt.OrderedSet[string]
Name string
Args []string
Env dt.OrderedMap[string, string]
Directory string
Input io.Reader
Output io.Writer
Error io.Writer
}
Command describes an external process. All fields are public and may be set directly, or through the fluent builder methods. Always set, at least, 'Name' before calling 'Run', 'Exec, or 'Start'.
The methods all return the same *Command pointer, so calls can be chained: new(Command).WithName("echo").WithArgs("hello").
func (*Command) Clone ¶
Clone returns a new Command with all fields copied. The Args slice is cloned so mutations to one do not affect the other. Input, Output, and Error share the same underlying io.Reader/Writer values as the original, since those cannot be meaningfully copied.
func (*Command) Exec ¶
Exec runs the command and returns its stdout as a reader. Both stdout and stderr are buffered internally. If the process fails, Exec returns a nil reader and an *Error containing the captured stderr, stdout, and the underlying exec error. On success the returned reader contains stdout.
func (*Command) Format ¶
Format implements fmt.Formatter. For %v and %+v the exc.Command<[+ID][+LABELS] command>. %q encloses with brackets.)
func (*Command) ResentEnv ¶
ResentEnv clears all explicitly set environment variables and returns the receiver. After this call the process inherits the parent environment.
func (*Command) ResetLabels ¶
ResetLabels removes all labels from the command and returns the receiver.
func (*Command) ResetStdError ¶
ResetStdError clears the stderr writer and returns the receiver.
func (*Command) ResetStdInput ¶
ResetStdInput clears the stdin reader and returns the receiver.
func (*Command) ResetStdOutput ¶
ResetStdOutput clears the stdout writer and returns the receiver.
func (*Command) Resolve ¶
Resolve builds an *exec.Cmd from the Command fields without running it. Useful when you need direct access to the underlying exec.Cmd, for example to set additional fields before calling Start or Run yourself.
func (*Command) Run ¶
Run executes the command, waits for it to finish, and returns any error. stdout and stderr are routed to cmd.Output and cmd.Error respectively, or discarded if those fields are nil. Use Exec to capture output as a reader, or Start for non-blocking execution.
func (*Command) SSH ¶
SSH sets the command to ssh and passes host followed by args directly to the ssh binary. host may include a user prefix (user@host). args may contain ssh options, a remote command, or both, in the order ssh expects them.
func (*Command) SetEnvVar ¶
SetEnvVar adds or replaces an environment variable in the command's explicit environment and returns the receiver. Variables set here are passed to the process instead of inheriting the parent environment.
func (*Command) Shell ¶
Shell runs code using the specified shell (or path to shell binary,) and runs the 'block' accordingly (via the '-c' option). Usable with bash/zsh/dash/sh/nu/fish/python/python3.
func (*Command) Start ¶
Start launches the command asynchronously and returns a fnx.Worker that blocks until the process exits or the worker's context is cancelled. If the command fails to start, a worker that immediately returns the start error is returned. Cancelling the context passed to Start terminates the process; cancelling the context passed to the returned worker unblocks the caller without killing the process.
func (*Command) UnsetEnvVar ¶
UnsetEnvVar removes an environment variable from the command's explicit environment and returns the receiver.
func (*Command) WithArgs ¶
WithArgs replaces the argument list with the provided values and returns the receiver.
func (*Command) WithDirectory ¶
WithDirectory sets the working directory for the process and returns the receiver.
func (*Command) WithID ¶
WithID sets the user-supplied identifier for the command and returns the receiver. The ID is not passed to the underlying process; it is used only for logging and formatting.
func (*Command) WithLabel ¶
WithLabel adds label to the command's label set and returns the receiver.
func (*Command) WithStdError ¶
WithStdError sets the writer that receives the process's stderr and returns the receiver. Pass nil to discard stderr.
func (*Command) WithStdInput ¶
WithStdInput sets the reader that is connected to the process's stdin and returns the receiver. Pass nil to use no stdin.
func (*Command) WithStdOutput ¶
WithStdOutput sets the writer that receives the process's stdout and returns the receiver. Pass nil to discard stdout.
type Error ¶
Error holds the diagnostic information from a failed Exec call.
func ResolveError ¶
ResolveError extracts an *Error from err if one appears anywhere in the error chain. Returns the *Error and true on success, or nil and false if err is nil or contains no *Error.
func (*Error) As ¶
As finds the first value in the underlying error's chain that matches target and sets target to that value, delegating to errors.As. This lets errors.As(extrErr, &target) extract typed errors from inside Err.
func (*Error) Error ¶
Error returns the string summary of the error including the name, the underlying error, and the captured stderr output.
Source Files