run

= 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()
----
+
Or:
+
[source, go]
----
	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
	defer cancel()
	out, err := run.CMDCtx(ctx, "./command", "arg1", "arg2").CombinedOutput()
----

.Run a command and pass a custom io.Writer to run:
[source, go]
----
	// Defaults to os.Stdout and os.Stderr
	err := run.CMD("./command", "arg1", "arg2").Run()

	// Combined output to myCombinedWriter
	err := run.CMD("./command", "arg1", "arg2").Run(myCombinedWriter)

	// Separate streams
	err := run.CMD("./command", "arg1", "arg2").Run(myStdoutWriter, myStderrWriter)
----

.Run command and only return Stdout but print Stderr to os.Stderr as it happends
[source, go]
----
	out, err := run.CMD("./command", "arg1", "arg2").STDOutOutput()
----

.Run command and only return Stdout but discard Stderr for quiet mode.
[source, go]
----
	out, err := run.CMD("./command", "arg1", "arg2").DiscardErr().STDOutOutput()
----

.Run command and only return Stdout but save Stderr output to the error object if there was an error
[source, go]
----
	out, err := run.CMD("./command", "arg1", "arg2").SaveErr().STDOutOutput()
	if err != nil {
		var exitErr *exec.ExitError
		if errors.As(err, &exitErr) {
			errOutput := exitErr.Stderr
			log.Printf("Failed with exit code: %d, full error output: %s\n", exitErr.ExitCode(), string(errOutput))
----

== Testing

A mocking function can be stored in the context and retrieved automatically:

. Store the mock function in the context:
+
[source, go]
----
		ctx := context.Background()
		mockR := run.CMD().Mock(func(r *run.RunInfo) error {
			r.Stdout.Write([]byte("hello world\n"))
			r.Stderr.Write([]byte("hola mundo\n"))
			return nil
		})
		ctx = run.ContextWithRunInfo(ctx, mockR)
----

. Automatically run the mock function if it exists in the context:
+
[source, go]
----
		r := run.CMDCtx(ctx, "ls", "./run")
		out, err := r.CombinedOutput()
		if err != nil {
			t.Errorf("unexpected error")
		}
		if string(out) != "hello world\nhola mundo\n" {
			t.Errorf("wrong output: %s\n", out)
		}
----

NOTE: Must use `run.CMDCtx` to automatically run the mock function if it exists in the context.
If the function doesn't exist it runs the command as usual.

== LICENSE

This file is part of run.

Copyright (C) 2020-2024  David Gamba Rios

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.