pipe

package module
Version: v2.0.0-...-3c2ca4d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 14, 2014 License: BSD-2-Clause Imports: 14 Imported by: 26

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

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL