pipe

Documentation

Overview

package pipe implements type-safe unix like resources standard streams and pipelines This can be used to write unix like tools communicating through Go native types which can be connected together like unix allows.

Example

ctx := context.Background()
cat := Lines{
	cat: []string{"three", "small", "pigs"},
}
wc := CountLines{}

out := &StringBuffer{}
stdio := NewStdio[string](
	nil,
	out,
	os.Stderr,
)

// an equivalent of cat | wc -l
// just using a native Go types and channels
err := NewLine[string]().Run(ctx, stdio, cat, wc)
if err != nil {
	log.Fatal(err)
}
fmt.Println(out.String())

Output:

3

Index

• Constants
• func Errors(err error) []error
• type Error
  • func FromError(x error) Error
  • func NewError(code int, err error) Error
  • func NewErrorf(code int, format string, args ...any) Error
  • func (e Error) Error() string
• type Filter
• type Line
  • func NewLine[T any]() Line[T]
  • func (p Line[T]) Pipefail(b bool) Line[T]
  • func (p Line[T]) Run(ctx context.Context, stdio StandardIO[T], filters ...Filter[T]) error
• type StandardIO
• type Stdio
  • func NewStdio[T any](stdin gio.Reader[T], stdout gio.Writer[T], stderr io.Writer) Stdio[T]
  • func (s Stdio[T]) Stderr() io.Writer
  • func (s Stdio[T]) Stdin() gio.Reader[T]
  • func (s Stdio[T]) Stdout() gio.Writer[T]

Examples

• Package
• Line (Nopipefail)
• Line (Pipefail)

Constants

const (
	// NotExecutable is from POSIX and indicates tool was found, but not executable
	NotExecutable = 126
	// NotFound is from POSIX and indicate a tool was not found
	NotFound = 127
	// UnknownError is a code used for unpacking other than pipe.Error
	UnknownError = 250
)

Functions

func Errors

func Errors(err error) []error

Errors returns a slice of errors if err is Error and member Err implements Unwrap []error otherwise returns nil even for non-nil errors

Types

type Error

type Error struct {
	Code int
	Err  error
}

Error is a common error type returned by pipeline. It has a Code for unix compatibility and an error.

func FromError

func FromError(x error) Error

FromError unpacks error into Error. If it can't be unpacked, it assigns code 250 error fs.ErrPermission will get code NotExecutable (126) error exec.ErrNotFound will get code NotFound (127) *exec.ExitError will be converted to Error with Code: ExitCode Error will be returned unchanged all other error (including nil) will be returned with code UnknownError

func NewError

func NewError(code int, err error) Error

NewError returns a new error with code and error inside

func NewErrorf

func NewErrorf(code int, format string, args ...any) Error

NewErrorf returns formatted new error with code and error inside

func (Error) Error

func (e Error) Error() string

type Filter

type Filter[T any] interface {
	Run(context.Context, StandardIO[T]) error
}

type Line

type Line[T any] struct {
	// contains filtered or unexported fields
}

pipe.Line implements the unix-like pipeline for command | command2 | command3 by connecting the filters via gio.Pipe

Example (Nopipefail)

ctx := context.Background()
cat := Lines{
	cat: []string{"three", "small", "pigs"},
}
fail := Fail{err: io.EOF}
wc := CountLines{}

out := &StringBuffer{}
stdio := NewStdio[string](
	nil,
	out,
	os.Stderr,
)

// an equivalent of false | cat | wc -l
err := NewLine[string]().Pipefail(false).Run(ctx, stdio, fail, cat, wc)
if err != nil {
	log.Fatal(err)
}
fmt.Println("OK")

Output:

OK

Example (Pipefail)

ctx := context.Background()
cat := Lines{
	cat: []string{"three", "small", "pigs"},
}
fail := Fail{err: io.EOF}
wc := CountLines{}

out := &StringBuffer{}
stdio := NewStdio[string](
	nil,
	out,
	os.Stderr,
)

// an equivalent of set -o pipefail; false | cat | wc -l
err := NewLine[string]().Pipefail(true).Run(ctx, stdio, fail, cat, wc)
if err == nil {
	log.Fatal("expected err, got nil")
}
fmt.Println(err)

Output:

Error{Code: 1, Err: EOF}

func NewLine

func NewLine[T any]() Line[T]

func (Line[T]) Pipefail

func (p Line[T]) Pipefail(b bool) Line[T]

Pipefail - true (the default) is an equivalent of set -o pipefail, so pipe is canceled on a first error and this is returned upper. To simulate default shell behavior use Pipefail(false). Which does not cancel the pipe and returns the last error.

func (Line[T]) Run

func (p Line[T]) Run(ctx context.Context, stdio StandardIO[T], filters ...Filter[T]) error

Run joins all filters via gio.Pipe with a stdio. Each filter runs in own goroutine and function returns on all. The returned error depends on Pipefail value

true (the default) - returns nil if none of commands fail, otherwise returns all errors in a pipe in a slice. If the first failure is Error, then it's Code is returned. otherwise code 1 is used.

false - returns error of a last command. If the error is nil, then result of the call is nil. for non nil errors, it returns a slice of all errors and a code or 1 depending on a type of last error.

type StandardIO

type StandardIO[T any] interface {
	Stdin() gio.Reader[T]
	Stdout() gio.Writer[T]
	Stderr() io.Writer
}

pipe.StandardIO is a standard unix-like type safe input and output defines three streams

stdin - from which can be read
stdout - to which results should be written
stderr - standard io.Writer for errors, debugs and so

type Stdio

type Stdio[T any] struct {
	// contains filtered or unexported fields
}

Stdio represent type safe unix-like standard input and output Implements gio.Standard[T] interface

func NewStdio

func NewStdio[T any](stdin gio.Reader[T], stdout gio.Writer[T], stderr io.Writer) Stdio[T]

func (Stdio[T]) Stderr

func (s Stdio[T]) Stderr() io.Writer

func (Stdio[T]) Stdin

func (s Stdio[T]) Stdin() gio.Reader[T]

func (Stdio[T]) Stdout

func (s Stdio[T]) Stdout() gio.Writer[T]