README
¶
shell
This package allows you to run shell commands easily and concisely. You can specify arguments, environment variables, and working directry. You can also get the exit code, stdout, and any error.
The biggest advantage of using this package over the built-in os/exec is testability and brevity.
Quick Start
Running a command:
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
func main() {
exitcode, stdout, err := shell.Run(context.Background(), "date", "-u")
if err != nil {
panic(err)
}
fmt.Printf("[%d] %s\n", exitcode, stdout)
}
Running a command with environment variables:
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
func main() {
opts := shell.RunOptions{
Environment: map[string]string{
"GREETING": "Hello, World!",
},
}
exitcode, stdout, err := shell.RunWith(context.Background(), opts, "printenv", "GREETING")
if err != nil {
panic(err)
}
fmt.Printf("[%d] %s\n", exitcode, stdout)
}
Building a command and unit testing:
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
type service struct {
funcs struct {
ls shell.RunnerWithFunc
}
}
func newService() *service {
s := new(service)
s.funcs.ls = shell.RunnerWith("ls")
s.funcs.ls = s.funcs.ls.WithArgs("-a")
return s
}
func (s *service) list(path string) (string, error) {
opts := shell.RunOptions{WorkingDir: path}
_, stdout, err := s.funcs.ls(context.Background(), opts)
return stdout, err
}
func main() {
s := newService()
out, err := s.list("/opt")
if err != nil {
panic(err)
}
fmt.Println(out)
}
package main
import (
"context"
"testing"
"github.com/gardenbed/charm/shell"
)
func TestService_List(t *testing.T) {
t.Run("Success", func(t *testing.T) {
s := new(service)
s.funcs.ls = func(context.Context, shell.RunOptions, ...string) (int, string, error) {
return 0, "foo bar", nil
}
out, err := s.list("/test")
if out != "foo bar" || err != nil {
t.Fail()
}
})
}
Documentation
¶
Overview ¶
Package shell provides helper functions for running shell commands.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run executes a command in the default shell. It returns the exit code, output, and error (if any).
Example ¶
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
func main() {
_, out, _ := shell.Run(context.Background(), "echo", "foo", "bar")
fmt.Println(out)
}
Output:
func RunWith ¶
func RunWith(ctx context.Context, opts RunOptions, command string, args ...string) (int, string, error)
RunWith executes a command with given options in the default shell. It returns the exit code, output, and error (if any).
Example ¶
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
func main() {
opts := shell.RunOptions{
Environment: map[string]string{
"PLACEHOLDER": "foo bar",
},
}
_, out, _ := shell.RunWith(context.Background(), opts, "printenv", "PLACEHOLDER")
fmt.Println(out)
}
Output:
Types ¶
type RunOptions ¶
type RunOptions struct {
// WorkingDir is the working directory for a command.
WorkingDir string
// Environment is a map of key-values representing environment variables for a command.
Environment map[string]string
}
RunOptions are optional settings for a command.
type RunnerFunc ¶
RunnerFunc is a function for running a bounded command.
func Runner ¶
func Runner(command string, args ...string) RunnerFunc
Runner binds a command to a list of arguments and returns a function. The returned function can be used for running the bounded command in the default shell.
Example ¶
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
func main() {
echo := shell.Runner("echo", "foo", "bar")
_, out, _ := echo(context.Background(), "baz")
fmt.Println(out)
}
Output:
func (RunnerFunc) WithArgs ¶
func (f RunnerFunc) WithArgs(args ...string) RunnerFunc
WithArgs binds more arguments to a Runner function and returns a new Runner function.
Example ¶
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
func main() {
echo := shell.Runner("echo", "foo")
echo = echo.WithArgs("bar")
_, out, _ := echo(context.Background(), "baz")
fmt.Println(out)
}
Output:
type RunnerWithFunc ¶
RunnerWithFunc is a function for running a bounded command with given options.
func RunnerWith ¶
func RunnerWith(command string, args ...string) RunnerWithFunc
RunnerWith binds a command to a list of arguments with given options and returns a function. The returned function can be used for running the bounded command in the default shell.
Example ¶
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
func main() {
opts := shell.RunOptions{
Environment: map[string]string{
"TOKEN": "access-token",
},
}
printenv := shell.RunnerWith("printenv")
_, out, _ := printenv(context.Background(), opts, "TOKEN")
fmt.Println(out)
}
Output:
func (RunnerWithFunc) WithArgs ¶
func (f RunnerWithFunc) WithArgs(args ...string) RunnerWithFunc
WithArgs binds more arguments to a RunnerWith function and returns a new RunnerWith function.
Example ¶
package main
import (
"context"
"fmt"
"github.com/gardenbed/charm/shell"
)
func main() {
opts := shell.RunOptions{
Environment: map[string]string{
"TOKEN": "access-token",
},
}
printenv := shell.RunnerWith("printenv")
printenv = printenv.WithArgs("TOKEN")
_, out, _ := printenv(context.Background(), opts)
fmt.Println(out)
}
Output:
Source Files