README
¶
Package xc is os/exec, but with fewer features (and vowels).
The goal is to make common (to me!) exec tasks simple, with richer errors available.
If it is useful for your tasks, great! If not, that's fine. Use os/exec.
Inspired by https://github.com/earthboundkid/requests and by having to write a lot of os/exec recently.
Status: definitely experimental. Use with caution.
License: MIT
Documentation
¶
Overview ¶
Package xc is os/exec, but with fewer features (and vowels).
The goal is to make common (to me!) exec tasks simple, with richer error handling.
If it is useful for your tasks, great! If not, that's fine. Use os/exec.
Index ¶
- type Builder
- func (b *Builder) AppendArgf(format string, args ...any) *Builder
- func (b *Builder) AppendArgs(args ...string) *Builder
- func (b *Builder) AppendEnv(env ...string) *Builder
- func (b *Builder) AppendEnvKV(kv ...string) *Builder
- func (b *Builder) CombineOutput() *Builder
- func (b *Builder) Describe(description string) *Builder
- func (b *Builder) Describef(format string, args ...any) *Builder
- func (b *Builder) Dir(dir string) *Builder
- func (b *Builder) Run() *Result
- func (b *Builder) Stderr(w io.Writer) *Builder
- func (b *Builder) Stdin(r io.Reader) *Builder
- func (b *Builder) StdinBytes(buf []byte) *Builder
- func (b *Builder) StdinString(s string) *Builder
- func (b *Builder) Stdout(w io.Writer) *Builder
- type Error
- type Result
- func (r *Result) AllowExitCodes(codes ...int) *Result
- func (r *Result) Bytes() ([]byte, error)
- func (r *Result) ExitCode() int
- func (r *Result) Split(sep string) ([]string, error)
- func (r *Result) SplitBytes(sep string) ([][]byte, error)
- func (r *Result) String() (string, error)
- func (r *Result) TrimSpace() *Result
- func (r *Result) Wait() error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder provides a fluent interface for configuring commands.
func (*Builder) AppendArgf ¶
AppendArgf adds a single argument fmt.Sprintf-style.
func (*Builder) AppendArgs ¶
AppendArgs adds additional arguments to the command.
func (*Builder) AppendEnv ¶
AppendEnv adds environment variables to the command's environment. Each entry should be in the form "KEY=VALUE".
func (*Builder) AppendEnvKV ¶
AppendEnvKV adds environment variables to the command's environment. AppendEnvKV takes a slice of alternating key-value pairs. If the length of the slice is odd, AppendEnvKV will panic.
func (*Builder) CombineOutput ¶
CombineOutput combines stderr into stdout in the output. Doing this makes stderr unavailable in error messages. Calling CombineOutput after Stdout or Stderr will panic.
func (*Builder) Describef ¶
Describef adds a fmt.Sprintf-style description of the command to the error message.
func (*Builder) Run ¶
Run runs the command. It always returns a non-nil Result. It does not block. Instead, most Result methods block.
func (*Builder) Stderr ¶
Stderr writes error output to the given writer. Using a custom stderr will cause many Result methods to become unavailable. Calling Stderr after CombineOutput will panic.
func (*Builder) StdinBytes ¶
StdinBytes sets a byte slice as the input that will be provided to the command.
func (*Builder) StdinString ¶
StdinString sets a string as the input that will be provided to the command.
type Error ¶
type Error struct {
// Frame contains the runtime.Frame of the code that called Run.
Frame runtime.Frame
// Command contains a string description of the command that was run.
// It is meant for human consumption, not parsing.
Command string
// LaunchErr contains errors that occurred before the command started.
LaunchErr error
// ExecErr contains errors that occurred while the command was running.
ExecErr error
// APIError contains errors that occurred due to API misuse.
APIError error
// Stderr contains the buffered error output of the command.
// It may be nil, e.g. if Builder.Stderr or Builder.CombineOutput was called.
Stderr *bytes.Buffer
// Description contains a description of the command's intent.
Description string
}
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
A Result contains the output of a command. All Result methods that return errors always return an *Error.
func (*Result) AllowExitCodes ¶
AllowExitCodes allows the command to exit "successfully", i.e. with no error, with the given exit codes.
func (*Result) ExitCode ¶
ExitCode returns the exit code of the command. If the command did not start, or the exit code is not available, for example because the command was terminated, it returns -1.
func (*Result) SplitBytes ¶
SplitBytes splits the output of the command by the given separator.
Source Files