cmder

README

Cmder

Cmder implements builder functionality wrapping os/exec for easily constructing shell commands. The initial intended use for this package was simple scripting with Mage, but there is nothing that should stop it from being used in other implementations.

Heavily inspired by Mage's own sh library and many more great projects who have come before.

Usage

Examples

Examples can be found in the _examples/magefile.go Magefile.

Run the following to execute any of the example targets from the above Magefile.

cd _examples
mage -l

Additionally many of the tests can provide some example usage.

Logging

Cmder logs all commands being run, using the Logger method, which implements the Logger interface:

type Logger interface {
  // Log inserts a log entry. Arguments may be handled in the manner
  // of fmt.Print, but the underlying logger may also decide to handle
  // them differently.
  Log(v ...interface{})

  // Logf inserts a log entry. Arguments are handled in the manner of
  // fmt.Printf.
  Logf(format string, v ...interface{})
}

By default (if none specified with the Cmder.Logger() method) the built-in logger will be used. See Additional log.Logger* variables for configuration options.

Color is disabled by default, but can be enabled by setting either MAGEFILE_ENABLE_COLOR or CMDER_ENABLE_COLOR environment variables to true.

The default logger will check the terminal width and if the command to be printed is wider than the terminal width, it will be broken up into multiple lines, similar to a shell command represented on multiple lines.

Contributing

See CONTRIBUTING.md. Contributors should follow the Go Community Code of Conduct .

Tests

Requires:

• mage
• golangci-lint

Run:

mage check

Documentation

Overview

Package cmder implements builder functionality wrapping os/exec for easily constructing shell commands

Index

• func DryRun()
• func SetLogger(l log.Logger)
• type Cmder
  • func New(command ...string) Cmder

Functions

func DryRun

func DryRun()

DryRun will ensure that the commands executed will log, but not be executed in the scope of the package

func SetLogger

func SetLogger(l log.Logger)

SetLogger allows for setting the cmder from an external implementation

Types

type Cmder

type Cmder interface {
	// Args appends additional arguments to the given command
	Args(...string) Cmder

	// Ctx can be used to pass context to the underlying exec command. The Run method will call
	// exec.CommandContext with the given context
	Ctx(context.Context) Cmder

	// CombinedOutput runs the command and returns its combined
	// standard output and standard error.
	CombinedOutput() ([]byte, error)

	// Complete returns a boolean value as to whether the command has complete it's execution
	Complete() bool

	// Clone returns a new Cmder copied from the original
	Clone() Cmder

	// Dir specifies the working directory of the command.
	//
	// If Dir is not set, Run runs the command in the
	// calling process's current directory.
	Dir(string) Cmder

	// DryRun sets the current Cmder instance to run in DryRun mode (log and skip execution)
	//
	// Option to pass one or more strings to replace the dryrun action key
	// defaults to LoggerDryRunKey
	DryRun(...string) Cmder

	// Duration returns the duration in time.Duration the command took to run
	// if it has completed.
	Duration() time.Duration

	// Env appends the given strings to the environment of the process
	//
	// Each entry is of the form "key=value".
	//
	// The new process uses the calling process's environment in addition
	// to the keys provided by Env.
	//
	// If Env contains duplicate environment keys, only the last
	// value in the slice for each duplicate key is used.
	Env(...string) Cmder

	// ExitCode returns the exit code of the command. If Run has not been invoked
	// zero will always be returned.
	ExitCode() int

	// In connects the new process' stdin to the current process's stdin if no input provided.
	// If input provided the input will be passed to the new process' stdin.
	In(...byte) Cmder

	// Out connects the new process' stdout and optionally stderr to the given io.Writers
	// Useful for writing to buffer or files
	Out(stdout io.Writer, stderr ...io.Writer) Cmder

	// Kill invokes the os.exec Kill method on the command
	//
	// Kill causes the Process to exit immediately.
	// Kill does not wait until the Process has actually exited.
	// This only kills the Process itself, not any other processes it may have started.
	Kill() error

	// LogCmder will print the command that is to be executed.
	// Included in Run if Silent unset
	// See also String, LogCmd
	LogCmd()

	// Allows setting an external logger.
	// See the Logger interface for more details.
	Logger(log.Logger) Cmder

	// Output invokes the os.exec Output method on the command
	//
	// Output runs the command and returns its stdout.
	// Any returned error will usually be of type *exec.ExitError.
	Output() ([]byte, error)

	// Pid returns the process id of the exited process or nil if the process has yet to exit.
	// See also
	// - Process
	// - https://pkg.go.dev/os#Process
	Pid() *int

	// Process is the underlying process, once started.
	// See also: https://pkg.go.dev/os#Process
	Process() *os.Process

	// Run invokes the os.exec Run method on the command
	//
	// Run calls exec.Run starting the specified command and waits for it to complete.
	// If Silent not set, the command will be printed prior to execution.
	//
	// Optionally one or two io.Writer may be passed to Run where
	// the first being stdout and the second being stderr.
	// If only one specified it will be connected to the processes' stdout and stderr.
	//
	// The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, and exits with a zero exit status.
	//
	// If the command starts but does not complete successfully, the error is of type *ExitError. Other error types may be returned for other situations.
	//
	// If the calling goroutine has locked the operating system thread with runtime.LockOSThread and modified any inheritable OS-level thread state (for example, Linux or Plan 9 name spaces), the new process will inherit the caller's thread state.
	Run(...io.Writer) error

	// RunFn returns a function to call Run with the given command
	// optionally appending any new args and returning an error.
	// When the function is invoked a new underlying command is created
	// in order to retain the state of the original.
	//
	// Optionally one or two io.Writer may be passed to Run where
	// the first being stdout and the second being stderr.
	// If only one specified it will be connected to the processes' stdout and stderr.
	//
	// Can be useful in defining a command once and calling it
	// multiple times or ways.
	//
	// See also: RunFnWithCmd
	RunFn(...io.Writer) func(args ...string) error

	// RunFnCmd returns a function to call Run with the given command
	// optionally appending any new args and returning the new command
	// and a possible error.
	// When the function is invoked a new underlying command is created
	// in order to retain the state of the original.
	//
	// Optionally one or two io.Writer may be passed to Run where
	// the first being stdout and the second being stderr.
	// If only one specified it will be connected to the processes' stdout and stderr.
	//
	// Can be useful in defining a command once and calling it
	// multiple times or ways.
	//
	// See also: RunFn
	RunFnCmd(...io.Writer) func(args ...string) (Cmder, error)

	// Silent will set Run to not print the command prior to execution
	Silent() Cmder

	// Start invokes the os.exec Start method on the command
	//
	// Start starts the specified command but does not wait for it to complete.
	//
	// If Start returns successfully, the Process method will be set.
	//
	// The Wait method will return the exit code and release associated resources
	// once the command exits.
	//
	// Optionally one or two io.Writer may be passed to Run where
	// the first being stdout and the second being stderr.
	// If only one specified it will be connected to the processes' stdout and stderr.
	//
	Start(...io.Writer) error

	// StartFn returns a function to call Run with the given command
	// optionally appending any new args and returning an error.
	// When the function is invoked a new underlying command is created
	// in order to retain the state of the original.
	//
	// Optionally one or two io.Writer may be passed to Run where
	// the first being stdout and the second being stderr.
	// If only one specified it will be connected to the processes' stdout and stderr.
	//
	// Can be useful in defining a command once and calling it
	// multiple times or ways.
	//
	// See also: StartFnCmd, RunFun, RunFnWithCmd
	StartFn(w ...io.Writer) func(args ...string) error

	// StartFnCmd returns a function to call Run with the given command
	// optionally appending any new args and returning the new command
	// and a possible error.
	// When the function is invoked a new underlying command is created
	// in order to retain the state of the original.
	//
	// Optionally one or two io.Writer may be passed to Run where
	// the first being stdout and the second being stderr.
	// If only one specified it will be connected to the processes' stdout and stderr.
	//
	// Can be useful in defining a command once and calling it
	// multiple times or ways.
	//
	// See also: StartFn, RunFnCmd, RunFn
	StartFnCmd(...io.Writer) func(args ...string) (Cmder, error)

	// String returns a human-readable description of the command
	// from exec.Cmder. It is intended only for debugging.
	// In particular, it is not suitable for use as input to a shell.
	// The output of String may vary across Go releases.
	// See also: DryRun
	String() string

	// Wait invokes the os.exec Wait method on the command
	//
	// Wait waits for the command to exit and waits for any copying to
	// stdin or copying from stdout or stderr to complete.
	//
	// The command must have been started by Start.
	//
	// The returned error is nil if the command runs, has no problems
	// copying stdin, stdout, and stderr, and exits with a zero exit
	// status.
	//
	// If the command fails to run or doesn't complete successfully, the
	// error is of type *ExitError. Other error types may be
	// returned for I/O problems.
	//
	// If any of c.Stdin, c.Stdout or c.Stderr are not an *os.File, Wait also waits
	// for the respective I/O loop copying to or from the process to complete.
	//
	// Wait releases any resources associated with the Cmd.
	Wait() error
}

Cmder the os/exec shell command builder interface

func New

func New(command ...string) Cmder

New returns a new os/exec builder command implemented using the Cmder interface