run

README

= Run

image:https://pkg.go.dev/badge/github.com/DavidGamba/dgtools/run.svg[Go Reference, link="https://pkg.go.dev/github.com/DavidGamba/dgtools/run"]

Provides a wrapper around os/exec with method chaining for modifying behaviour.

Import: `github.com/DavidGamba/dgtools/run`

== Examples

.Run command and only return Stdout
[source, go]
----
	out, err := run.CMD("./command", "arg1", "arg2").STDOutOutput()
----

.Run command and combine Stderr and Stdout
[source, go]
----
	out, err := run.CMD("./command", "arg1", "arg2").CombinedOutput()
----

.Run command and change Working Directory
[source, go]
----
	out, err := run.CMD("./command", "arg1", "arg2").Dir("..").CombinedOutput()
----

.Run command and set environment variables
[source, go]
----
	out, err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").CombinedOutput()
----

.Run command and log the command that is going to be executed to os.Stderr
[source, go]
----
	out, err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().CombinedOutput()
----

.Run command and override the default Logger
[source, go]
----
	run.Logger = log.New(os.Stderr, "", log.LstdFlags)
	out, err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().CombinedOutput()
----

.Run command without trapping its output
[source, go]
----
	err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().Run()
----

.Run command interactively by tying Stdin
[source, go]
----
	err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().Stdin().Run()
----

.Pass data ([]byte) directly to the Stdin of the command
[source, go]
----
	err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().In(data).CombinedOutput()
----

.Run a command with a cancelation context
[source, go]
----
	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
	defer cancel()
	out, err := run.CMD("./command", "arg1", "arg2").Ctx(ctx).CombinedOutput()
----

Documentation

Overview

Package run provides a wrapper around os/exec with method chaining for modifying behaviour.

Index

• Variables
• type RunInfo
  • func CMD(cmd ...string) *RunInfo
  • func (r *RunInfo) CombinedOutput() ([]byte, error)
  • func (r *RunInfo) Ctx(ctx context.Context) *RunInfo
  • func (r *RunInfo) Dir(dir string) *RunInfo
  • func (r *RunInfo) Env(env ...string) *RunInfo
  • func (r *RunInfo) In(input []byte) *RunInfo
  • func (r *RunInfo) Log() *RunInfo
  • func (r *RunInfo) Run() error
  • func (r *RunInfo) STDOutOutput() ([]byte, error)
  • func (r *RunInfo) Stdin() *RunInfo

Variables

var Logger = log.New(os.Stderr, "", log.LstdFlags)

Types

type RunInfo

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

func CMD

func CMD(cmd ...string) *RunInfo

func (*RunInfo) CombinedOutput

func (r *RunInfo) CombinedOutput() ([]byte, error)

CombinedOutput - Runs given CMD and returns STDOut and STDErr combined.

func (*RunInfo) Ctx

func (r *RunInfo) Ctx(ctx context.Context) *RunInfo

Ctx - specifies the context of the command to allow for timeouts.

func (*RunInfo) Dir

func (r *RunInfo) Dir(dir string) *RunInfo

Dir - specifies the working directory of the command.

func (*RunInfo) Env

func (r *RunInfo) Env(env ...string) *RunInfo

Env - Add key=value pairs to the environment of the process.

func (*RunInfo) In

func (r *RunInfo) In(input []byte) *RunInfo

In - Pass input to stdin.

func (*RunInfo) Log

func (r *RunInfo) Log() *RunInfo

func (*RunInfo) Run

func (r *RunInfo) Run() error

Run - wrapper around os/exec CMD.Run()

Run starts the specified command and waits for it to complete.

The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, and exits with a zero exit status.

If the command starts but does not complete successfully, the error is of type *ExitError. Other error types may be returned for other situations.

func (*RunInfo) STDOutOutput

func (r *RunInfo) STDOutOutput() ([]byte, error)

STDOutOutput - Runs given CMD and returns STDOut only.

func (*RunInfo) Stdin

func (r *RunInfo) Stdin() *RunInfo

Stdin - connect caller's os.Stdin to command stdin.