Documentation
¶
Overview ¶
Package exec provides an easy way to execute commands, improving the ease-of-use and error handling of the standard library os/exec package. For example:
err := exec.Run("git", "commit", "-am")
// or
err := exec.RunSh("git commit -am")
// or
err := exec.Verbose().Run("git", "commit", "-am")
Index ¶
- func Args(cfg *Config, str string) []string
- func CmdRan(err error) bool
- func Exec(cmd string, args ...string) (ran bool, err error)
- func ExitStatus(err error) int
- func LookPath(file string) (string, error)
- func MkdirAll(path string, perm os.FileMode) error
- func Output(cmd string, args ...string) (string, error)
- func PrintCmd(cmd string, err error)
- func RemoveAll(path string) error
- func Run(cmd string, args ...string) error
- func RunSh(cstr string) error
- func SetMajor(c *Config)
- func SetMinor(c *Config)
- func SetSilent(c *Config)
- func SetVerbose(c *Config)
- type Config
- func (c *Config) Exec(cmd string, args ...string) (ran bool, err error)
- func (c *Config) GetWriter(w io.Writer, err error) io.Writer
- func (c *Config) MkdirAll(path string, perm os.FileMode) error
- func (c *Config) OutCmd(cmd string, args ...string) func(args ...string) (string, error)
- func (c *Config) Output(cmd string, args ...string) (string, error)
- func (c *Config) PrintCmd(cmd string, err error)
- func (c *Config) RemoveAll(path string) error
- func (c *Config) Run(cmd string, args ...string) error
- func (c *Config) RunCmd(cmd string, args ...string) func(args ...string) error
- func (c *Config) RunSh(cstr string) error
- func (t *Config) SetBuffer(v bool) *Config
- func (t *Config) SetCommands(v io.Writer) *Config
- func (t *Config) SetDir(v string) *Config
- func (c *Config) SetEnv(key, val string) *Config
- func (t *Config) SetErrors(v io.Writer) *Config
- func (t *Config) SetFatal(v bool) *Config
- func (t *Config) SetPrintOnly(v bool) *Config
- func (t *Config) SetStderr(v io.Writer) *Config
- func (t *Config) SetStdin(v io.Reader) *Config
- func (t *Config) SetStdout(v io.Writer) *Config
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CmdRan ¶
CmdRan examines the error to determine if it was generated as a result of a command running via os/exec.Command. If the error is nil, or the command ran (even if it exited with a non-zero exit code), CmdRan reports true. If the error is an unrecognized type, or it is an error from exec.Command that says the command failed to run (usually due to the command not existing or not being executable), it reports false.
func Exec ¶
Exec calls Config.Exec on Major
func ExitStatus ¶
ExitStatus returns the exit status of the error if it is an exec.ExitError or if it implements ExitStatus() int. 0 if it is nil or 1 if it is a different error.
func LookPath ¶
LookPath searches for an executable named file in the directories named by the PATH environment variable. If file contains a slash, it is tried directly and the PATH is not consulted. Otherwise, on success, the result is an absolute path.
In older versions of Go, LookPath could return a path relative to the current directory. As of Go 1.19, LookPath will instead return that path along with an error satisfying errors.Is(err, ErrDot). See the package documentation for more details.
func MkdirAll ¶
MkdirAll calls Config.MkdirAll on Major
func Output ¶
Output calls Config.Output on Major
func SetMajor ¶
func SetMajor(c *Config)
SetMajor sets the config object that Major returns. It should be used sparingly, and only in cases where there is a clear property that should be set for all commands. If the given config object is nil, Major will go back to returning its default value.
func SetMinor ¶
func SetMinor(c *Config)
SetMinor sets the config object that Minor returns. It should be used sparingly, and only in cases where there is a clear property that should be set for all commands. If the given config object is nil, Minor will go back to returning its default value.
func SetSilent ¶
func SetSilent(c *Config)
SetSilent sets the config object that Silent returns. It should be used sparingly, and only in cases where there is a clear property that should be set for all commands. If the given config object is nil, Silent will go back to returning its default value.
func SetVerbose ¶
func SetVerbose(c *Config)
SetVerbose sets the config object that Verbose returns. It should be used sparingly, and only in cases where there is a clear property that should be set for all commands. If the given config object is nil, Verbose will go back to returning its default value.
Types ¶
type Config ¶
type Config struct {
// Buffer is whether to buffer the output of Stdout and Stderr,
// which is necessary for the correct printing of commands and output
// when there is an error with a command, and for correct coloring
// on Windows. Therefore, it should be kept at the default value of
// true in most cases, except for when a command will run for a log
// time and print output throughout (eg: a log command).
Buffer bool
// Fatal is whether to fatally exit programs with [os.Exit] and an
// exit code of 1 when there is an error running a command. It should
// only be used by end-user apps, not libraries, which should use more
// robust and idiomatic error handling.
Fatal bool
// PrintOnly is whether to only print commands that would be run and
// not actually run them. It can be used, for example, for safely testing
// an app.
PrintOnly bool
// The directory to execute commands in. If it is unset,
// commands are run in the current directory.
Dir string
// Env contains any additional environment variables specified.
// The current environment variables will also be passed to the
// command, but they will be overridden by any variables here
// if there are conflicts.
Env map[string]string `set:"-"`
// Stdout is the writer to write the standard output of called commands to.
// It can be set to nil to disable the writing of the standard output.
Stdout io.Writer
// Stderr is the writer to write the standard error of called commands to.
// It can be set to nil to disable the writing of the standard error.
Stderr io.Writer
// Stdin is the reader to use as the standard input.
Stdin io.Reader
// Commands is the writer to write the string representation of the called commands to.
// It can be set to nil to disable the writing of the string representations of the called commands.
Commands io.Writer
// Errors is the writer to write program errors to.
// It can be set to nil to disable the writing of program errors.
Errors io.Writer
}
Config contains the configuration information that controls the behavior of exec. It is passed to most high-level functions, and a default version of it can be easily constructed using [DefaultConfig].
func Major ¶
func Major() *Config
Major returns the default Config object for a major command, based on logx.UserLevel. It should be used for commands that are central to an app's logic and are more important for the user to know about and be able to see the output of. It results in commands and output being printed with a logx.UserLevel of slog.LevelInfo or below, whereas Minor results in that when it is slog.LevelDebug or below. Most commands in a typical use case should be Major, which is why the global helper functions operate on it. The object returned by Major is guaranteed to be unique, so it can be modified directly.
func Minor ¶
func Minor() *Config
Minor returns the default Config object for a minor command, based on logx.UserLevel. It should be used for commands that support an app behind the scenes and are less important for the user to know about and be able to see the output of. It results in commands and output being printed with a logx.UserLevel of slog.LevelDebug or below, whereas Major results in that when it is slog.LevelInfo or below. The object returned by Minor is guaranteed to be unique, so it can be modified directly.
func Silent ¶
func Silent() *Config
Silent returns the default Config object for a silent command, based on logx.UserLevel. It should be used for commands that whose output/input is private and needs to be always hidden from the user; for example, for a command that involves passwords. It results in commands and output never being printed. The object returned by Silent is guaranteed to be unique, so it can be modified directly.
func Verbose ¶
func Verbose() *Config
Verbose returns the default Config object for a verbose command, based on logx.UserLevel. It should be used for commands whose output are central to an application; for example, for a logger or app runner. It results in commands and output being printed with a logx.UserLevel of slog.LevelWarn or below, whereas Major and Minor result in that when it is slog.LevelInfo and [slog.levelDebug] or below, respectively. The object returned by Verbose is guaranteed to be unique, so it can be modified directly.
func (*Config) Exec ¶
Exec executes the command, piping its stdout and stderr to the config writers. If the command fails, it will return an error with the command output. The given cmd and args may include references to environment variables in $FOO format, in which case these will be expanded before the command is run.
Ran reports if the command ran (rather than was not found or not executable). Code reports the exit code the command returned if it ran. If err == nil, ran is always true and code is always 0.
func (*Config) GetWriter ¶
GetWriter returns the appropriate writer to use based on the given writer and error. If the given error is non-nil, the returned writer is guaranteed to be non-nil, with [Config.Stderr] used as a backup. Otherwise, the returned writer will only be non-nil if the passed one is.
func (*Config) MkdirAll ¶
MkdirAll is a helper function that calls os.MkdirAll and Config.PrintCmd.
func (*Config) PrintCmd ¶
PrintCmd uses [GetWriter] to print the given command to [Config.Commands] or [Config.Stderr], based on the given error and the config settings. A newline is automatically inserted.
func (*Config) RemoveAll ¶
RemoveAll is a helper function that calls os.RemoveAll and Config.PrintCmd.
func (*Config) Run ¶
Run runs the given command using the given configuration information and arguments.
func (*Config) RunCmd ¶
RunCmd returns a function that will call Run with the given command. This is useful for creating command aliases to make your scripts easier to read, like this:
// in a helper file somewhere
var g0 = sh.RunCmd("go") // go is a keyword :(
// somewhere in your main code
if err := g0("install", "github.com/gohugo/hugo"); err != nil {
return err
}
Args passed to command get baked in as args to the command when you run it. Any args passed in when you run the returned function will be appended to the original args. For example, this is equivalent to the above:
var goInstall = sh.RunCmd("go", "install") goInstall("github.com/gohugo/hugo")
RunCmd uses Exec underneath, so see those docs for more details.
func (*Config) RunSh ¶
RunSh runs given full command string with args formatted as in a standard shell command
func (*Config) SetBuffer ¶
SetBuffer sets the [Config.Buffer]: Buffer is whether to buffer the output of Stdout and Stderr, which is necessary for the correct printing of commands and output when there is an error with a command, and for correct coloring on Windows. Therefore, it should be kept at the default value of true in most cases, except for when a command will run for a log time and print output throughout (eg: a log command).
func (*Config) SetCommands ¶
SetCommands sets the [Config.Commands]: Commands is the writer to write the string representation of the called commands to. It can be set to nil to disable the writing of the string representations of the called commands.
func (*Config) SetDir ¶
SetDir sets the [Config.Dir]: The directory to execute commands in. If it is unset, commands are run in the current directory.
func (*Config) SetErrors ¶
SetErrors sets the [Config.Errors]: Errors is the writer to write program errors to. It can be set to nil to disable the writing of program errors.
func (*Config) SetFatal ¶
SetFatal sets the [Config.Fatal]: Fatal is whether to fatally exit programs with os.Exit and an exit code of 1 when there is an error running a command. It should only be used by end-user apps, not libraries, which should use more robust and idiomatic error handling.
func (*Config) SetPrintOnly ¶
SetPrintOnly sets the [Config.PrintOnly]: PrintOnly is whether to only print commands that would be run and not actually run them. It can be used, for example, for safely testing an app.
func (*Config) SetStderr ¶
SetStderr sets the [Config.Stderr]: Stderr is the writer to write the standard error of called commands to. It can be set to nil to disable the writing of the standard error.
Source Files