pipe.v2: gopkg.in/pipe.v2 Index | Files

package pipe

import "gopkg.in/pipe.v2"

Package pipe implements unix-like pipelines for Go.

See the documentation for details:

http://labix.org/pipe

Index

Package Files

pipe.go

Variables

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

func CombinedOutput Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Output runs the p pipe and returns its stdout output.

See functions Run, CombinedOutput, and DividedOutput.

func OutputTimeout Uses

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 Uses

func Run(p Pipe) error

Run runs the p pipe discarding its output.

See functions Output, CombinedOutput, and DividedOutput.

func RunTimeout Uses

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.

type Errors Uses

type Errors []error

func (Errors) Error Uses

func (e Errors) Error() string

type OutputBuffer Uses

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 Uses

func (out *OutputBuffer) Bytes() []byte

Bytes returns all the data written to out.

func (*OutputBuffer) Write Uses

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

Writes appends b to out's buffered data.

type Pipe Uses

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 Uses

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 Uses

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 Uses

func Discard() Pipe

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

func Exec Uses

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

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

func Filter Uses

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 Uses

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 Uses

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 Uses

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 Uses

func Print(args ...interface{}) Pipe

Print provides args to fmt.Sprint and writes the resuling string to the pipe's stdout.

func Printf Uses

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 Uses

func Println(args ...interface{}) Pipe

Println provides args to fmt.Sprintln and writes the resuling string to the pipe's stdout.

func Read Uses

func Read(r io.Reader) Pipe

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

func ReadFile Uses

func ReadFile(path string) Pipe

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

func RenameFile Uses

func RenameFile(fromPath, toPath string) Pipe

RenameFile renames the file fromPath as toPath.

func Replace Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func Write(w io.Writer) Pipe

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

func WriteFile Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

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

func (*State) Kill Uses

func (s *State) Kill()

Kill sends a kill notice to all pending tasks.

func (*State) Path Uses

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 Uses

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 Uses

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

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

type Task Uses

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.

Package pipe imports 14 packages (graph) and is imported by 17 packages. Updated 2016-07-15. Refresh now. Tools for package owners.