README

Installation and usage

See gopkg.in/pipe.v2 for documentation and usage details.

Expand ▾ Collapse ▴

Documentation

Overview

    Package pipe implements unix-like pipelines for Go.

    See the documentation for details:

    http://labix.org/pipe
    

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	ErrTimeout = errors.New("timeout")
    	ErrKilled  = errors.New("explicitly killed")
    )

    Functions

    func CombinedOutput

    func CombinedOutput(p Pipe) ([]byte, error)

      CombinedOutput runs the p pipe and returns its stdout and stderr outputs merged together.

      See functions Run, Output, and DividedOutput.

      func CombinedOutputTimeout

      func CombinedOutputTimeout(p Pipe, timeout time.Duration) ([]byte, error)

        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

        func DividedOutput(p Pipe) (stdout []byte, stderr []byte, err error)

          DividedOutput runs the p pipe and returns its stdout and stderr outputs.

          See functions Run, Output, and CombinedOutput.

          func DividedOutputTimeout

          func DividedOutputTimeout(p Pipe, timeout time.Duration) (stdout []byte, stderr []byte, err error)

            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

            func Output(p Pipe) ([]byte, error)

              Output runs the p pipe and returns its stdout output.

              See functions Run, CombinedOutput, and DividedOutput.

              func OutputTimeout

              func OutputTimeout(p Pipe, timeout time.Duration) ([]byte, error)

                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.

                func Run

                func Run(p Pipe) error

                  Run runs the p pipe discarding its output.

                  See functions Output, CombinedOutput, and DividedOutput.

                  func RunTimeout

                  func RunTimeout(p Pipe, timeout time.Duration) error

                    RunTimeout runs the p pipe discarding its output.

                    The pipe is killed if it takes longer to run than the provided timeout.

                    See functions OutputTimeout, CombinedOutputTimeout, and DividedOutputTimeout.

                    Types

                    type Errors

                    type Errors []error

                    func (Errors) Error

                    func (e Errors) Error() string

                    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.

                        func (*OutputBuffer) Write

                        func (out *OutputBuffer) Write(b []byte) (n int, err error)

                          Writes appends b to out's buffered data.

                          type Pipe

                          type Pipe func(s *State) error

                            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

                            func AppendFile(path string, perm os.FileMode) Pipe

                              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

                              func ChDir(dir string) Pipe

                                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 Discard

                                func Discard() Pipe

                                  Discard reads data from the pipe's stdin and discards it.

                                  func Exec

                                  func Exec(name string, args ...string) Pipe

                                    Exec returns a pipe that runs the named program with the given arguments.

                                    func Filter

                                    func Filter(f func(line []byte) bool) Pipe

                                      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

                                      func Line(p ...Pipe) Pipe

                                        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

                                        func MkDir(dir string, perm os.FileMode) Pipe

                                          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

                                          func MkDirAll(dir string, perm os.FileMode) Pipe

                                            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

                                              func Printf(format string, args ...interface{}) Pipe

                                                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 Read

                                                  func Read(r io.Reader) Pipe

                                                    Read reads data from r and writes it to the pipe's stdout.

                                                    func ReadFile

                                                    func ReadFile(path string) Pipe

                                                      ReadFile reads data from the file at path and writes it to the pipe's stdout.

                                                      func RenameFile

                                                      func RenameFile(fromPath, toPath string) Pipe

                                                        RenameFile renames the file fromPath as toPath.

                                                        func Replace

                                                        func Replace(f func(line []byte) []byte) Pipe

                                                          Replace filters lines read from the pipe's stdin and writes the returned values to stdout.

                                                          func Script

                                                          func Script(p ...Pipe) Pipe

                                                            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

                                                            func SetEnvVar(name string, value string) Pipe

                                                              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

                                                              func System(cmd string) Pipe

                                                                System returns a pipe that runs cmd via a system shell. It is equivalent to the pipe Exec("/bin/sh", "-c", cmd).

                                                                func TaskFunc

                                                                func TaskFunc(f func(s *State) error) Pipe

                                                                  TaskFunc is a helper to define a Pipe that adds a Task with f as its Run method.

                                                                  func Tee

                                                                  func Tee(w io.Writer) Pipe

                                                                    Tee reads data from the pipe's stdin and writes it both to the pipe's stdout and to w.

                                                                    func TeeAppendFile

                                                                    func TeeAppendFile(path string, perm os.FileMode) Pipe

                                                                      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

                                                                      func TeeWriteFile(path string, perm os.FileMode) Pipe

                                                                        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.

                                                                        func Write

                                                                        func Write(w io.Writer) Pipe

                                                                          Write writes to w the data read from the pipe's stdin.

                                                                          func WriteFile

                                                                          func WriteFile(path string, perm os.FileMode) Pipe

                                                                            WriteFile writes to the file at path the data read from the pipe's stdin. 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

                                                                              func NewState(stdout, stderr io.Writer) *State

                                                                                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

                                                                                func (s *State) AddTask(t Task) error

                                                                                  AddTask adds t to be run concurrently with other tasks as appropriate for the pipe.

                                                                                  func (*State) EnvVar

                                                                                  func (s *State) EnvVar(name string) string

                                                                                    EnvVar returns the value for the named environment variable in s.

                                                                                    func (*State) Kill

                                                                                    func (s *State) Kill()

                                                                                      Kill sends a kill notice to all pending tasks.

                                                                                      func (*State) Path

                                                                                      func (s *State) Path(path ...string) string

                                                                                        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.

                                                                                        func (*State) RunTasks

                                                                                        func (s *State) RunTasks() error

                                                                                          RunTasks runs all pending tasks registered via AddTask. This is called by the pipe running functions and generally there's no reason to call it directly.

                                                                                          func (*State) SetEnvVar

                                                                                          func (s *State) SetEnvVar(name, value string)

                                                                                            SetEnvVar sets the named environment variable to the given value in s.

                                                                                            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