binwrapper

README

go-binwrapper

A lightweight Go wrapper around command-line executables. Provides a fluent API for argument management, stdin/stdout/stderr handling, timeout support, environment configuration, and process lifecycle control.

Inspired by the npm package bin-wrapper.

Install

go get github.com/nickalie/go-binwrapper

Usage

Basic execution

bin := binwrapper.NewBinWrapper().ExecPath("echo")

err := bin.Run("hello", "world")
fmt.Println(string(bin.StdOut())) // "hello world\n"

Specifying binary location

Use Dest to set the directory containing the binary. If omitted, the executable is looked up in PATH.

bin := binwrapper.NewBinWrapper().
    Dest("/usr/local/bin").
    ExecPath("mytool")

Pre-configured arguments

Arguments added with Arg are prepended to every Run call.

bin := binwrapper.NewBinWrapper().
    ExecPath("echo").
    Arg("-n", "hello")

bin.Run("world")
fmt.Println(string(bin.StdOut())) // "hello world"

Capturing stderr and combined output

bin := binwrapper.NewBinWrapper().
    ExecPath("sh").
    Arg("-c", "echo out && echo err >&2")

bin.Run()

fmt.Println(string(bin.StdOut()))         // "out\n"
fmt.Println(string(bin.StdErr()))         // "err\n"
fmt.Println(string(bin.CombinedOutput())) // "out\nerr\n"

Providing stdin

bin := binwrapper.NewBinWrapper().
    ExecPath("cat").
    StdIn(strings.NewReader("input data"))

bin.Run()
fmt.Println(string(bin.StdOut())) // "input data"

Redirecting stdout to a writer

When SetStdOut is used, output goes directly to the writer instead of being captured in StdOut().

var buf bytes.Buffer
bin := binwrapper.NewBinWrapper().
    ExecPath("echo").
    SetStdOut(&buf)

bin.Run("hello")
fmt.Println(buf.String()) // "hello\n"

Timeouts

Returns context.DeadlineExceeded if the command exceeds the timeout.

bin := binwrapper.NewBinWrapper().
    ExecPath("sleep").
    Timeout(2 * time.Second)

err := bin.Run("60")
// err == context.DeadlineExceeded

Environment variables

bin := binwrapper.NewBinWrapper().
    ExecPath("sh").
    Arg("-c", "echo $MY_VAR").
    Env([]string{"MY_VAR=hello"})

bin.Run()
fmt.Println(string(bin.StdOut())) // "hello\n"

Reuse with Reset

Reset clears arguments, stdio, environment, and captured output so the wrapper can be reused.

bin := binwrapper.NewBinWrapper().ExecPath("echo")

bin.Run("first")
fmt.Println(string(bin.StdOut())) // "first\n"

bin.Reset()
bin.Run("second")
fmt.Println(string(bin.StdOut())) // "second\n"

Process control

// Kill a running process
bin.Kill()

Windows support

AutoExe automatically appends .exe to the executable path on Windows.

bin := binwrapper.NewBinWrapper().
    AutoExe().
    ExecPath("mytool") // becomes "mytool.exe" on Windows

Debug mode

bin := binwrapper.NewBinWrapper().
    ExecPath("mytool").
    Debug() // prints the full command before execution

API

Method	Description
NewBinWrapper()	Create a new instance
Dest(path)	Set the directory containing the binary
ExecPath(name)	Set the executable name
AutoExe()	Append .exe on Windows
Arg(name, values...)	Add command-line arguments
Args()	Get current arguments
Path()	Get the full path to the binary
Run(args...)	Execute the binary
Kill()	Terminate the running process
Timeout(d)	Set execution timeout
StdIn(reader)	Set stdin source
StdOut()	Get captured stdout
StdErr()	Get captured stderr
CombinedOutput()	Get stdout + stderr combined
SetStdOut(writer)	Redirect stdout to a writer
Env(vars)	Set environment variables
Debug()	Enable debug output
Reset()	Clear state for reuse

All setter methods return *BinWrapper for chaining.

License

MIT

Documentation

Overview

Package binwrapper provides an executable wrapper with convenient methods for running command line tools and capturing their output. Inspired by and partially ported from npm package bin-wrapper: https://github.com/kevva/bin-wrapper

Index

• type BinWrapper
  • func NewBinWrapper() *BinWrapper
  • func (b *BinWrapper) Arg(name string, values ...string) *BinWrapper
  • func (b *BinWrapper) Args() []string
  • func (b *BinWrapper) AutoExe() *BinWrapper
  • func (b *BinWrapper) CombinedOutput() []byte
  • func (b *BinWrapper) Debug() *BinWrapper
  • func (b *BinWrapper) Dest(dest string) *BinWrapper
  • func (b *BinWrapper) Dir(dir string) *BinWrapper
  • func (b *BinWrapper) Env(env []string) *BinWrapper
  • func (b *BinWrapper) ExecPath(execPath string) *BinWrapper
  • func (b *BinWrapper) Kill() error
  • func (b *BinWrapper) Path() string
  • func (b *BinWrapper) Reset() *BinWrapper
  • func (b *BinWrapper) Run(arg ...string) error
  • func (b *BinWrapper) SetStdOut(writer io.Writer) *BinWrapper
  • func (b *BinWrapper) StdErr() []byte
  • func (b *BinWrapper) StdIn(reader io.Reader) *BinWrapper
  • func (b *BinWrapper) StdOut() []byte
  • func (b *BinWrapper) Timeout(timeout time.Duration) *BinWrapper

Types

type BinWrapper

type BinWrapper struct {
	// contains filtered or unexported fields
}

BinWrapper wraps executable and provides convenient methods to interact with

func NewBinWrapper

func NewBinWrapper() *BinWrapper

NewBinWrapper creates BinWrapper instance

func (*BinWrapper) Arg

func (b *BinWrapper) Arg(name string, values ...string) *BinWrapper

Arg adds command line argument to run the binary with.

func (*BinWrapper) Args

func (b *BinWrapper) Args() []string

Args returns arguments were added with Arg method

func (*BinWrapper) AutoExe

func (b *BinWrapper) AutoExe() *BinWrapper

AutoExe adds .exe extension for windows executable path

func (*BinWrapper) CombinedOutput

func (b *BinWrapper) CombinedOutput() []byte

CombinedOutput returns combined executable's stdout and stderr

func (*BinWrapper) Debug

func (b *BinWrapper) Debug() *BinWrapper

Debug enables debug output

func (*BinWrapper) Dest

func (b *BinWrapper) Dest(dest string) *BinWrapper

Dest accepts a path which the binary is located in

func (*BinWrapper) Dir

func (b *BinWrapper) Dir(dir string) *BinWrapper

Dir specifies the working directory of the executable. If Dir is empty, Run uses the calling process's current directory.

func (*BinWrapper) Env

func (b *BinWrapper) Env(env []string) *BinWrapper

Env specifies the environment of the executable. If Env is nil, Run uses the current process's environment. Elements of env should be in form: "ENV_VARIABLE_NAME=value"

func (*BinWrapper) ExecPath

func (b *BinWrapper) ExecPath(execPath string) *BinWrapper

ExecPath define a file to use as the binary

func (*BinWrapper) Kill

func (b *BinWrapper) Kill() error

Kill terminates the process

func (*BinWrapper) Path

func (b *BinWrapper) Path() string

Path returns the full path to the binary

func (*BinWrapper) Reset

func (b *BinWrapper) Reset() *BinWrapper

Reset removes arguments, stdin, stdout writer, env, and clears captured stdout/stderr

func (*BinWrapper) Run

func (b *BinWrapper) Run(arg ...string) error

Run runs the binary with provided arg list. Arg list is appended to args set through Arg method Returns context.DeadlineExceeded in case of timeout

func (*BinWrapper) SetStdOut

func (b *BinWrapper) SetStdOut(writer io.Writer) *BinWrapper

SetStdOut set writer to write executable's stdout

func (*BinWrapper) StdErr

func (b *BinWrapper) StdErr() []byte

StdErr returns the executable's stderr after Run was called

func (*BinWrapper) StdIn

func (b *BinWrapper) StdIn(reader io.Reader) *BinWrapper

StdIn sets reader to read executable's stdin from

func (*BinWrapper) StdOut

func (b *BinWrapper) StdOut() []byte

StdOut returns the binary's stdout after Run was called

func (*BinWrapper) Timeout

func (b *BinWrapper) Timeout(timeout time.Duration) *BinWrapper

Timeout sets timeout for the command. By default it's 0 (binary will run till end).