run

README

Shell script-like command execution in Golang

Documentation

Index

• func Exec(args ...string) error
• func ExecAll(commands Cmds) (error, int)
• func Out(args ...string) string
• func OutAll(commands Cmds) (string, error, int)
• func OutErr(args ...string) (string, error)
• func OutQuiet(args ...string) string
• type Args
  • func (a Args) List() []string
  • func (a Args) ListEq() []string
• type Cmds

Examples

• ExecAll
• ExecAll (First_Fail)
• ExecAll (Last_Fail)
• ExecAll (Mid_Fail)
• Out
• Out (With_Error)
• OutAll
• OutErr
• OutErr (With_Error)
• OutQuiet
• OutQuiet (With_Error)

Functions

func Exec

func Exec(args ...string) error

Exec checks for existence of first argument as an executable on the system and then runs it with Go's exec.Command.Run exiting in a way that is supported across all architectures that Go supports. The stdin, stdout, and stderr are connected directly to that of the calling program. Sometimes this is insufficient and the UNIX-specific SysExec is preferred.

func ExecAll

func ExecAll(commands Cmds) (error, int)

ExecAll simulates short-circuit logic popular in shell scripting by returning the first error encountered while attempting to run each command line from the commands list in sequential order. The index of the last command executed is returned as well. Note that an empty list of Cmds is a valid argument (where the integer returned will be 0).

Example

err, n := run.ExecAll(run.Cmds{{`ls`, `-d`, `/tmp`}, {`true`}, {`echo`, `wow`}})
fmt.Println(err, n)

Output:

/tmp
wow
<nil> 2

Example (First_Fail)

err, n := run.ExecAll(run.Cmds{{`ls`, `notme`}, {`true`}, {`echo`, `it works`}})
fmt.Println(err, n)

Output:

exit status 2 0

Example (Last_Fail)

err, n := run.ExecAll(run.Cmds{{`ls`, `-d`, `/tmp`}, {`true`}, {`ls`, `bork`}})
fmt.Println(err, n)

Output:

/tmp
exit status 2 2

Example (Mid_Fail)

err, n := run.ExecAll(run.Cmds{{`ls`, `-d`, `/tmp`}, {`false`}, {`echo`, `it works`}})
fmt.Println(err, n)

Output:

/tmp
exit status 1 1

func Out

func Out(args ...string) string

Out returns the standard output of the executed command as a string. Errors are logged after the command completes but not returned. See OutErr. For more current error messages during execution use Exec instead.

Example

out := run.Out(`ls`, `-d`, `/tmp`)
fmt.Printf("%q", out)

Output:

"/tmp\n"

Example (With_Error)

out := run.Out(`ls`, `-d`, `/nopenothear`)
// note the output to stderr
fmt.Printf("%q", out)

Output:

""

func OutAll

func OutAll(commands Cmds) (string, error, int)

OutAll returns the collective standard output of the executed commands as a string or the first error encountered along with the index in Cmds of the command arguments that produced the error. See OutErr.

Example

buf, err, n := run.OutAll(run.Cmds{{`ls`, `-d`, `/tmp`}, {`true`}, {`echo`, `wow`}})
fmt.Printf("%q %v %v", buf, err, n)

Output:

"/tmp\nwow\n" <nil> 2

func OutErr

func OutErr(args ...string) (string, error)

OutErr returns the standard output of the executed command as a string along with any error returned.

Example

out, err := run.OutErr(`ls`, `-d`, `/tmp`)
fmt.Printf("%q %v", out, err)

Output:

"/tmp\n" <nil>

Example (With_Error)

out, err := run.OutErr(`ls`, `-d`, `/nopenothear`)
fmt.Printf("%q %v", out, err)

Output:

"" exit status 2

func OutQuiet

func OutQuiet(args ...string) string

OutQuiet returns the standard output of the executed command as a string without logging any errors. Always returns a string even if empty. See OutErr.

Example

out := run.OutQuiet(`ls`, `-d`, `/tmp`)
fmt.Printf("%q", out)

Output:

"/tmp\n"

Example (With_Error)

out := run.OutQuiet(`ls`, `-d`, `/nopenothear`)
fmt.Printf("%q", out)

Output:

""

Types

type Args

type Args map[string]string

Args encapsulates the possible long-form options that can be passed to anything on the command line. Empty strings are valid values. To omit an argument ensure that it no longer exists in the map [delete(map,key)]. For more complex handling of options consider using a command-line arguments handling package.

func (Args) List

func (a Args) List() []string

List returns the expanded keys and values as a list of valid arguments with the keys converted into double-dash (long-form) arguments (ex: --foo bar)

func (Args) ListEq

func (a Args) ListEq() []string

ListEq returns the expanded keys and values as a list of valid arguments with the keys converted into double-dash (long-form) arguments that are joined to their value with an equal sign (ex: --foo=bar).

type Cmds

type Cmds [][]string

Cmds is list of string lists to be used with the *All functions where each string list contains a list of arguments to be passed to Exec (or equivalent).