README
¶
Installation and usage
See gopkg.in/pipe.v2 for documentation and usage details.
Documentation
¶
Overview ¶
Package pipe implements unix-like pipelines for Go.
See the documentation for details:
http://labix.org/pipe
Index ¶
- Variables
- func CombinedOutput(p Pipe) ([]byte, error)
- func CombinedOutputTimeout(p Pipe, timeout time.Duration) ([]byte, error)
- func DividedOutput(p Pipe) (stdout []byte, stderr []byte, err error)
- func DividedOutputTimeout(p Pipe, timeout time.Duration) (stdout []byte, stderr []byte, err error)
- func Output(p Pipe) ([]byte, error)
- func OutputTimeout(p Pipe, timeout time.Duration) ([]byte, error)
- func Run(p Pipe) error
- func RunTimeout(p Pipe, timeout time.Duration) error
- type Errors
- type OutputBuffer
- type Pipe
- func AppendFile(path string, perm os.FileMode) Pipe
- func ChDir(dir string) Pipe
- func Discard() Pipe
- func Exec(name string, args ...string) Pipe
- func Filter(f func(line []byte) bool) Pipe
- func Line(p ...Pipe) Pipe
- func MkDir(dir string, perm os.FileMode) Pipe
- func MkDirAll(dir string, perm os.FileMode) Pipe
- func Print(args ...interface{}) Pipe
- func Printf(format string, args ...interface{}) Pipe
- func Println(args ...interface{}) Pipe
- func Read(r io.Reader) Pipe
- func ReadFile(path string) Pipe
- func RenameFile(fromPath, toPath string) Pipe
- func Replace(f func(line []byte) []byte) Pipe
- func Script(p ...Pipe) Pipe
- func SetEnvVar(name string, value string) Pipe
- func System(cmd string) Pipe
- func TaskFunc(f func(s *State) error) Pipe
- func Tee(w io.Writer) Pipe
- func TeeAppendFile(path string, perm os.FileMode) Pipe
- func TeeWriteFile(path string, perm os.FileMode) Pipe
- func Write(w io.Writer) Pipe
- func WriteFile(path string, perm os.FileMode) Pipe
- type State
- type Task
Constants ¶
This section is empty.
Variables ¶
var ( ErrTimeout = errors.New("timeout") ErrKilled = errors.New("explicitly killed") )
Functions ¶
func CombinedOutput ¶
CombinedOutput runs the p pipe and returns its stdout and stderr outputs merged together.
See functions Run, Output, and DividedOutput.
func CombinedOutputTimeout ¶
CombinedOutputTimeout runs the p pipe and returns its stdout and stderr outputs merged together.
The pipe is killed if it takes longer to run than the provided timeout.
See functions RunTimeout, OutputTimeout, and DividedOutputTimeout.
func DividedOutput ¶
DividedOutput runs the p pipe and returns its stdout and stderr outputs.
See functions Run, Output, and CombinedOutput.
func DividedOutputTimeout ¶
DividedOutputTimeout runs the p pipe and returns its stdout and stderr outputs.
The pipe is killed if it takes longer to run than the provided timeout.
See functions RunTimeout, OutputTimeout, and CombinedOutputTimeout.
func Output ¶
Output runs the p pipe and returns its stdout output.
See functions Run, CombinedOutput, and DividedOutput.
func OutputTimeout ¶
OutputTimeout runs the p pipe and returns its stdout output.
The pipe is killed if it takes longer to run than the provided timeout.
See functions RunTimeout, CombinedOutputTimeout, and DividedOutputTimeout.
Types ¶
type OutputBuffer ¶
type OutputBuffer struct {
// contains filtered or unexported fields
}
OutputBuffer is a concurrency safe writer that buffers all input.
It is used in the implementation of the output functions.
func (*OutputBuffer) Bytes ¶
func (out *OutputBuffer) Bytes() []byte
Bytes returns all the data written to out.
type Pipe ¶
Pipe functions implement arbitrary functionality that may be integrated with pipe scripts and pipelines. Pipe functions must not block reading or writing to the state streams. These operations must be run from a Task.
func AppendFile ¶
AppendFile append to the end of the file at path the data read from the pipe's stdin. If the file doesn't exist, it is created with perm.
func ChDir ¶
ChDir changes the pipe's current directory. If dir is relative, the change is made relative to the pipe's previous current directory.
Other than it being the default current directory for new pipes, the working directory of the running process isn't considered or changed.
func Filter ¶
Filter filters lines read from the pipe's stdin so that only those for which f is true are written to the pipe's stdout. The line provided to f has '\n' and '\r' trimmed.
func Line ¶
Line creates a pipeline with the provided entries, where the stdout of entry N in the pipeline is connected to the stdin of entry N+1.
For example, the equivalent of "cat article.ps | lpr" is:
p := pipe.Line(
pipe.ReadFile("article.ps"),
pipe.Exec("lpr"),
)
output, err := pipe.CombinedOutput(p)
func MkDir ¶
MkDir creates dir with the provided perm bits. If dir is relative, the created path is relative to the pipe's current directory.
func MkDirAll ¶
MkDirAll creates the missing parents of dir and dir itself with the provided perm bits. If dir is relative, the created path is relative to the pipe's current directory.
func Print ¶
func Print(args ...interface{}) Pipe
Print provides args to fmt.Sprint and writes the resuling string to the pipe's stdout.
func Printf ¶
Printf provides format and args to fmt.Sprintf and writes the resulting string to the pipe's stdout.
func Println ¶
func Println(args ...interface{}) Pipe
Println provides args to fmt.Sprintln and writes the resuling string to the pipe's stdout.
func RenameFile ¶
RenameFile renames the file fromPath as toPath.
func Replace ¶
Replace filters lines read from the pipe's stdin and writes the returned values to stdout.
func Script ¶
Script creates a pipe sequence with the provided entries.
For example, the equivalent of "cat article.ps | lpr; mv article.ps{,.done}" is:
p := pipe.Script(
pipe.Line(
pipe.ReadFile("article.ps"),
pipe.Exec("lpr"),
),
pipe.RenameFile("article.ps", "article.ps.done"),
)
output, err := pipe.CombinedOutput(p)
func SetEnvVar ¶
SetEnvVar sets the value of the named environment variable in the pipe.
Other than it being the default for new pipes, the environment of the running process isn't consulted or changed.
func System ¶
System returns a pipe that runs cmd via a system shell. It is equivalent to the pipe Exec("/bin/sh", "-c", cmd).
func TeeAppendFile ¶
TeeAppendFile reads data from the pipe's stdin and writes it both to the pipe's stdout and to the file at path. If the file doesn't exist, it is created with perm.
func TeeWriteFile ¶
TeeWriteFile reads data from the pipe's stdin and writes it both to the pipe's stdout and to the file at path. If the file doesn't exist, it is created with perm.
type State ¶
type State struct {
// Stdin, Stdout, and Stderr represent the respective data streams
// that the Pipe may act upon. Reading from and/or writing to these
// streams must be done from within a Task registered via AddTask.
// The three streams are initialized by NewState and must not be nil.
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
// Dir represents the directory in which all filesystem-related
// operations performed by the Pipe must be run on. It defaults
// to the current directory, and may be changed by Pipe functions.
Dir string
// Env is the process environment in which all executions performed
// by the Pipe must be run on. It defaults to a copy of the
// environmnet from the current process, and may be changed by Pipe
// functions.
Env []string
// Timeout defines the amount of time to wait before aborting running tasks.
// If set to zero, the pipe will not be aborted.
Timeout time.Duration
// contains filtered or unexported fields
}
State defines the environment for Pipe functions to run on. Create a new State via the NewState function.
func NewState ¶
NewState returns a new state for running pipes with. The state's Stdout and Stderr are set to the provided streams, Stdin is initialized to an empty reader, and Env is initialized to the environment of the current process.
func (*State) AddTask ¶
AddTask adds t to be run concurrently with other tasks as appropriate for the pipe.
func (*State) Path ¶
Path returns the provided path relative to the state's current directory. If multiple arguments are provided, they're joined via filepath.Join. If path is absolute, it is taken by itself.
type Task ¶
type Task interface {
// Run runs the task concurrently with other tasks as appropriate
// for the pipe. Run may flow data from the input stream and/or
// to the output streams of the pipe, and it must block while doing
// so. It must return only after all of its activities have
// terminated completely.
Run(s *State) error
// Kill abruptly interrupts in-progress activities being done by Run.
// If Run is blocked simply reading from and/or writing to the state
// streams, Kill doesn't have to do anything as Run will be unblocked
// by the closing of the streams.
Kill()
}
A Task may be registered by a Pipe into a State to run any activity concurrently with other tasks. Tasks registered within the execution of a Script only run after the preceding entries in the same script have succeeded.
Source Files