README
¶
🏃♂️ run
A new way to execute commands in Go
Example usage
package main
import (
"bytes"
"context"
"fmt"
"io"
"log"
"os"
"github.com/sourcegraph/run"
)
func main() {
ctx := context.Background()
// Easily stream all output back to standard out
err := run.Cmd(ctx, "echo", "hello world").Run().Stream(os.Stdout)
if err != nil {
log.Fatal(err.Error())
}
// Or collect, map, and modify output, then collect string lines from it
lines, err := run.Cmd(ctx, "ls").Run().
Map(func(ctx context.Context, line []byte, dst io.Writer) (int, error) {
if !bytes.HasSuffix(line, []byte(".go")) {
return 0, nil
}
return dst.Write(bytes.TrimSuffix(line, []byte(".go")))
}).
Lines()
if err != nil {
log.Fatal(err.Error())
}
for i, l := range lines {
fmt.Printf("line %d: %q\n", i, l)
}
// Errors include standard error by default, so we can just stream stdout.
err = run.Cmd(ctx, "ls", "foobar").StdOut().Run().Stream(os.Stdout)
if err != nil {
println(err.Error()) // exit status 1: ls: foobar: No such file or directory
}
// Generate data from a file, replacing tabs with spaces for Markdown purposes
var exampleData bytes.Buffer
exampleData.Write([]byte(exampleStart + "\n\n```go\n"))
if err = run.Cmd(ctx, "cat", "cmd/example/main.go").Run().
Map(func(ctx context.Context, line []byte, dst io.Writer) (int, error) {
return dst.Write(bytes.ReplaceAll(line, []byte("\t"), []byte(" ")))
}).
Stream(&exampleData); err != nil {
log.Fatal(err)
}
exampleData.Write([]byte("```\n\n" + exampleEnd))
// Render new README file
var readmeData bytes.Buffer
if err = run.Cmd(ctx, "cat", "README.md").Run().Stream(&readmeData); err != nil {
log.Fatal(err)
}
replaced := exampleBlockRegexp.ReplaceAll(readmeData.Bytes(), exampleData.Bytes())
// Pipe data to command
err = run.Cmd(ctx, "cp /dev/stdin README.md").Input(bytes.NewReader(replaced)).Run().Wait()
if err != nil {
log.Fatal(err)
}
}
Documentation
¶
Index ¶
- func Arg(v string) string
- func ExitCode(err error) int
- type Command
- func (c *Command) Dir(dir string) *Command
- func (c *Command) Env(env map[string]string) *Command
- func (c *Command) Environ(environ []string) *Command
- func (c *Command) Input(input io.Reader) *Command
- func (c *Command) ResetInput() *Command
- func (c *Command) Run() Output
- func (c *Command) StdErr() *Command
- func (c *Command) StdOut() *Command
- type ExitCoder
- type LineMap
- type Output
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Arg ¶ added in v0.8.0
Arg quotes a value such that it gets treated as an argument by a command.
It is currently an alias for shell.Quote
func ExitCode ¶ added in v0.2.0
ExitCode returns the exit code associated with err if there is one, otherwise 1. If err is nil, returns 0.
In practice, this replicates the behaviour observed when running commands in the shell, running a command with an incorrect syntax for example will set $? to 1, which is what is expected in script. Not implementing this creates a confusing case where an error such as not finding the binary would either force the code to account for the absence of exit code, which defeats the purpose of this library which is to provide a convenient replacement for shell scripting.
Example ¶
package main
import (
"context"
"fmt"
"github.com/sourcegraph/run"
)
func main() {
ctx := context.Background()
err := run.Bash(ctx, "exit 123").Run().Wait()
fmt.Println(run.ExitCode(err))
err = run.Cmd(ctx, "echo", run.Arg("hello world!")).Run().Wait()
fmt.Println(run.ExitCode(err))
err = run.Cmd(ctx, "non-existing-binary").Run().Wait()
fmt.Println(run.ExitCode(err))
}
Output: 123 0 1
Types ¶
type Command ¶
type Command struct {
// contains filtered or unexported fields
}
Command builds a command for execution. Functions modify the underlying command.
func Bash ¶ added in v0.5.0
Bash joins all the parts and builds a command from it to be run by 'bash -c'.
Arguments are not implicitly quoted - to quote arguemnts, you can use Arg.
func Cmd ¶
Cmd joins all the parts and builds a command from it.
Arguments are not implicitly quoted - to quote arguemnts, you can use Arg.
func (*Command) Environ ¶
InheritEnv adds the given strings representing the environment (key=value) to the command, for example os.Environ().
func (*Command) Input ¶
Input pipes the given io.Reader to the command. If an input is already set, the given input is appended.
func (*Command) ResetInput ¶ added in v0.2.0
ResetInput sets the command's input to nil.
func (*Command) Run ¶
Run starts command execution and returns Output, which defaults to combined output.
type ExitCoder ¶ added in v0.2.0
ExitCoder is an error that also denotes an exit code to exit with. Users of Output can check if an error implements this interface to get the underlying exit code of a command execution.
For convenience, the ExitCode function can be used to get the code.
type LineMap ¶ added in v0.6.0
LineMap allows modifications of individual lines from Output and enables callbacks that operate on lines from Output. Bytes written to dst are collected and passed to subsequent LineMaps before being written to output aggregation, e.g. Output.Stream().
The return value mirrors the signature of (Writer).Write(), and should be used to indicate what was written to dst.
Errors interrupt line processing and are returned if and only if the command itself did not exit with an error.
type Output ¶
type Output interface {
// Map adds a LineMap function to be applied to this Output. It is only applied at
// aggregation time using e.g. Stream, Lines, and so on. Multiple LineMaps are applied
// sequentially, with the result of previous LineMaps propagated to subsequent
// LineMaps.
Map(f LineMap) Output
// Stream writes mapped output from the command to the destination writer until
// command completion.
Stream(dst io.Writer) error
// StreamLines writes mapped output from the command and sends it line by line to the
// destination callback until command completion.
StreamLines(dst func(line []byte)) error
// Lines waits for command completion and aggregates mapped output from the command as
// a slice of lines.
Lines() ([]string, error)
// Lines waits for command completion and aggregates mapped output from the command as
// a combined string.
String() (string, error)
// JQ waits for command completion executes a JQ query against the entire output.
//
// Refer to https://github.com/itchyny/gojq for the specifics of supported syntax.
JQ(query string) ([]byte, error)
// Reader is implemented so that Output can be provided directly to another Command
// using Input().
io.Reader
// WriterTo is implemented for convenience when chaining commands in LineMap.
io.WriterTo
// Wait waits for command completion and returns.
Wait() error
}
Output configures output and aggregation from a command.
It is behind an interface to more easily enable mock outputs and build different types of outputs, such as multi-outputs and error-only outputs, without complicating the core commandOutput implementation.
func NewErrorOutput ¶ added in v0.4.0
NewErrorOutput creates an Output that just returns error. Useful for allowing function that help run Commands and want to just return an Output even if errors can happen before command execution.
Source Files
Directories