README
¶
pygz/subprocess
About
subprocess is a Go library that returns standard output, standard error, and exit status code data from new 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 -u github.com/pygz/subprocess
Usage
subprocess exposes two public functions and a public struct with standard output, standard error, and exit status code response data from executable files that can be called on the command line. Full API documentation is available on GoDoc.
Import subprocess into your source files
package main
import (
"github.com/pygz/subprocess"
)
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.
package main
import (
"fmt"
"github.com/pygz/subprocess"
)
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)
}
package main
import (
"fmt"
"github.com/pygz/subprocess"
)
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. The shell can be modified 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. This flag can be modified in the shellflag parameter. Define the command to be executed as one or more parameters at the end of the function call.
package main
import (
"fmt"
"github.com/pygz/subprocess"
)
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)
}
package main
import (
"fmt"
"github.com/pygz/subprocess"
)
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)
}
package main
import (
"fmt"
"github.com/pygz/subprocess"
)
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)
}
package main
import (
"fmt"
"github.com/pygz/subprocess"
)
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 in order to execute this command.
The subprocess package is tested 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 new spawned system processes
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Response ¶
Response is a struct that is defined with data on 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 ¶
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 ¶ added in v0.2.0
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 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 as comma delimited parameters
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)
}
Source Files