subprocess

README

pygz/subprocess

About

subprocess is a Go library that returns standard output, standard error, and exit status code data from newly spawned processes on Linux, macOS, and Windows platforms. It was inspired by the Python subprocess standard library module.

The subprocess library API is versioned under the SemVer specification.

Install

The subprocess package does not include external dependencies. It is built with the Go standard library.

Install the subprocess library locally for testing and development use with the following command:

go get gopkg.in/pygz/subprocess.v1

Usage

subprocess exposes two public functions and a public struct with standard output, standard error, and exit status code data from executable files. Full API documentation is available on GoDoc.

Import subprocess into your source files

package main

import (
    "gopkg.in/pygz/subprocess.v1"
)

Public Data Types

subprocess.Response

The subprocess package defines the Response public data type with standard output, standard error, and exit status code fields. This is populated and returned to the calling code when you run an executable file with the public functions that are available in the subprocess package.

type Response struct {
    StdOut   string
    StdErr   string
    ExitCode int
}

Public Functions

subprocess.Run

func Run(executable string, args ...string) Response

The Run() function runs an executable file with optional arguments and returns the standard output, standard error, and exit status code data in a Response struct. Include one or more arguments to the executable as additional function parameters.

Example on macOS/Linux

package main

import (
    "fmt"
    "gopkg.in/pygz/subprocess.v1"
)

func main() {
    response := Run("ls", "-l")
    // print the standard output stream data
    fmt.Printf("%s", response.StdOut)
    // print the standard error stream data
    fmt.Printf("%s", response.StdErr)
    // print the exit status code integer value
    fmt.Printf("%d", response.ExitCode)
}

Example on Windows

package main

import (
    "fmt"
    "gopkg.in/pygz/subprocess.v1"
)

func main() {
    response := Run("dir", "/AD")
    // print the standard output stream data
    fmt.Printf("%s", response.StdOut)
    // print the standard error stream data
    fmt.Printf("%s", response.StdErr)
    // print the exit status code integer value
    fmt.Printf("%d", response.ExitCode)
}

subprocess.RunShell()

func RunShell(shell string, shellflag string, command ...string) Response

The RunShell() function runs an executable file with a shell and returns the standard output, standard error, and exit status code data in a Response struct. The default shell for Linux and macOS platforms is /bin/sh. The default shell for Windows is the cmd.exe command prompt. Modify the shell by defining the shell function parameter. A shell flag is included to indicate that the argument that follows is to be executed by the shell. The default flag on macOS and Linux platforms is -c. On Windows, this is /C. Modify the flag by defining the shellflag parameter. Define the command to be executed as one or more parameters at the end of the function call.

Example with the default shell on macOS/Linux

package main

import (
    "fmt"
    "gopkg.in/pygz/subprocess.v1"
)

func main() {
    response := RunShell("", "", "ls", "-l")
    // print the standard output stream data
    fmt.Printf("%s", response.StdOut)
    // print the standard error stream data
    fmt.Printf("%s", response.StdErr)
    // print the exit status code integer value
    fmt.Printf("%d", response.ExitCode)
}

Example with the default shell on Windows

package main

import (
    "fmt"
    "gopkg.in/pygz/subprocess.v1"
)

func main() {
    response := RunShell("", "", "dir", "/AD")
    // print the standard output stream data
    fmt.Printf("%s", response.StdOut)
    // print the standard error stream data
    fmt.Printf("%s", response.StdErr)
    // print the exit status code integer value
    fmt.Printf("%d", response.ExitCode)
}

Example with redefined shell on macOS/Linux

package main

import (
    "fmt"
    "gopkg.in/pygz/subprocess.v1"
)

func main() {
    response := RunShell("/usr/local/bin/zsh", "", "ls", "-l")
    // print the standard output stream data
    fmt.Printf("%s", response.StdOut)
    // print the standard error stream data
    fmt.Printf("%s", response.StdErr)
    // print the exit status code integer value
    fmt.Printf("%d", response.ExitCode)
}

Example with redefined shell on Windows

package main

import (
    "fmt"
    "gopkg.in/pygz/subprocess.v1"
)

func main() {
    response := RunShell("bash", "-c", "ls", "-l")
    // print the standard output stream data
    fmt.Printf("%s", response.StdOut)
    // print the standard error stream data
    fmt.Printf("%s", response.StdErr)
    // print the exit status code integer value
    fmt.Printf("%d", response.ExitCode)
}

Contributing

Contributions to the project are welcomed. Please submit changes in a pull request on the Github repository.

Testing

climock is a dependency that must be installed manually for the execution of subprocess package tests.

Install climock with:

$ go get -u github.com/chrissimpkins/climock

You can then execute source code unit tests and obtain source code coverage data locally by downloading the source repository and executing the following command in the root of the source repository:

$ go test -v -cover ./...

Go must be installed on your system to execute this command.

We test the subprocess package with Semaphore CI (Linux) and Appveyor CI (Windows). You may view the test results following the most recent commit (including commits proposed through a pull request) using those links.

Acknowledgments

The subprocess library was inspired by the Python standard library subprocess module. Source code for the exit status code retrieval was based on source discussed in the Stack Overflow posts here and here. A big thanks to Michael (@texhex) and JM (@jublo) for their input and feedback on the Windows platform support.

License

The subprocess library is licensed under the MIT license.

Documentation

Overview

Package subprocess provides support for standard output/error pipe data & exit status codes with newly spawned system processes

Index

• type Response
  • func Run(executable string, args ...string) Response
  • func RunShell(shell string, shellflag string, command ...string) Response

Types

type Response

type Response struct {
	StdOut   string
	StdErr   string
	ExitCode int
}

Response is a struct that is defined with data on the execution of the public Run and RunShell functions. It is returned from these public functions with the following data fields:

Response.StdOut - (string) standard output stream cast to a string
Response.StdErr - (string) standard error stream cast to a string
Response.ExitCode - (int) executable exit status code as an integer

func Run

func Run(executable string, args ...string) Response

Run is a public function that executes a system command and returns the standard output stream, standard error stream, and exit status code data in a returned subprocess.Response struct. Run takes the following parameters:

executable (string) - the executable for the command
args (...string) - one or more arguments to the executable as a comma-delimited list of parameters

Example:

func main() {
    response := Run("go", "--help")
    fmt.Printf("%s\n", response.StdOut)
    fmt.Printf("%s\n", response.StdErr)
    fmt.Printf("%d\n", response.ExitCode)
}

func RunShell

func RunShell(shell string, shellflag string, command ...string) Response

RunShell is a public function that executes a system command with a shell and returns the standard output stream, standard error stream, and exit status code data in a returned subprocess.Response struct. RunShell takes the following parameters:

shell (string) - path to the shell.  Defaults = /bin/sh on Linux, macOS; cmd.exe on Windows
shellflag (string) - flag to run executable file with shell. Default = `-c` (macOS/Linux); `/C` (Win)
command (...string) - one or more executable commands, comma-delimited parameter format

Example (macOS/Linux):

func main() {
    response := RunShell("", "", "ls", "-l")
    fmt.Printf("%s\n", response.StdOut)
    fmt.Printf("%s\n", response.StdErr)
    fmt.Printf("%d\n", response.ExitCode)
    response2 := RunShell("/usr/local/bin/zsh", "-c", "ls", "-l")
    fmt.Printf("%s\n", response.StdOut)
    fmt.Printf("%s\n", response.StdErr)
    fmt.Printf("%d\n", response.ExitCode)
}

Example (Windows):

func main() {
    response := RunShell("", "", "dir", "/AD")
    fmt.Printf("%s\n", response.StdOut)
    fmt.Printf("%s\n", response.StdErr)
    fmt.Printf("%d\n", response.ExitCode)
    response2 := RunShell("bash", "-c", "ls", "-l")
    fmt.Printf("%s\n", response.StdOut)
    fmt.Printf("%s\n", response.StdErr)
    fmt.Printf("%d\n", response.ExitCode)
}