README.adoc

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

	out, err := run.CMD("./command", "arg1", "arg2").STDOutOutput()

Run command and combine Stderr and Stdout

	out, err := run.CMD("./command", "arg1", "arg2").CombinedOutput()

Run command and change Working Directory

	out, err := run.CMD("./command", "arg1", "arg2").Dir("..").CombinedOutput()

Run command and set environment variables

	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

	out, err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().CombinedOutput()

Run command and override the default Logger

	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

	err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().Run()

Run command interactively by tying Stdin

	err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().Stdin().Run()

Pass data ([]byte) directly to the Stdin of the command

	err := run.CMD("./command", "arg1", "arg2").Dir("..").Env("DEBUG=true").Log().In(data).CombinedOutput()

Run a command with a cancelation context

	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
	defer cancel()
	out, err := run.CMD("./command", "arg1", "arg2").Ctx(ctx).CombinedOutput()

+ Or:

+

	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:

	// 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

	out, err := run.CMD("./command", "arg1", "arg2").STDOutOutput()

Run command and only return Stdout but discard Stderr for quiet mode.

	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

	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:

1. Store the mock function in the context:

   		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)

2. Automatically run the mock function if it exists in the context:

   		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 © 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/.