commandeer

README

commandeer

Go module to make running commands more endearing

An example of its use can be found at commandeer-example

Documentation

Index

• func LogToFile(fpath string, fname string) (io.Writer, error)
• type CmdCollection
• type CmdPkg
  • func NewPkg(l string) *CmdPkg
  • func (cp *CmdPkg) AddCmd(c string, e string, h bool, d time.Duration, t string) error
  • func (cp *CmdPkg) AddCmdWText(c string, e string, h bool, d time.Duration, t string, b string, a string) error
  • func (cp *CmdPkg) AddRedact(s string)
  • func (cp *CmdPkg) AddRedactSlice(s []string)
  • func (cp *CmdPkg) AddTarget(id string, dist string, rel string, os string, sh string)
  • func (cp *CmdPkg) ExecPkgCombined(t string) ([]byte, error)
  • func (cp *CmdPkg) ExecPkgError(t string) error
  • func (cp *CmdPkg) ExecPkgOnly(t string) error
  • func (cp *CmdPkg) ExecPkgStderr(t string) ([]byte, error)
  • func (cp *CmdPkg) ExecPkgStdout(t string) ([]byte, error)
  • func (cp *CmdPkg) LoadCmds(c []SingleCmd, t string) error
  • func (cp *CmdPkg) LogCmd(msg string)
  • func (cp *CmdPkg) LogError(msg string)
  • func (cp *CmdPkg) LogInfo(msg string)
  • func (cp *CmdPkg) LogTrace(msg string)
  • func (cp *CmdPkg) LogWarn(msg string)
  • func (cp *CmdPkg) Redactatron(l string) string
  • func (cp *CmdPkg) SetCmdLog(logHandler io.Writer)
  • func (cp *CmdPkg) SetLocation(cl Terminal)
  • func (cp *CmdPkg) SetLogging(logHandler io.Writer)
  • func (cp *CmdPkg) TurnOffRedaction()
  • func (cp *CmdPkg) TurnOnCmdLog()
• type LocalTerm
  • func (l *LocalTerm) ExecCombined(ctx context.Context, cmd string, shell string) ([]byte, error)
  • func (l *LocalTerm) ExecError(ctx context.Context, cmd string, shell string) error
  • func (i *LocalTerm) ExecOnly(ctx context.Context, cmd string, shell string)
  • func (l *LocalTerm) ExecStderr(ctx context.Context, cmd string, shell string) ([]byte, error)
  • func (l *LocalTerm) ExecStdout(ctx context.Context, cmd string, shell string) ([]byte, error)
• type MockTerm
  • func (m *MockTerm) ExecCombined(cxt context.Context, cmd string, shell string) ([]byte, error)
  • func (m *MockTerm) ExecError(ctx context.Context, cmd string, shell string) error
  • func (m *MockTerm) ExecOnly(ctx context.Context, cmd string, shell string)
  • func (m *MockTerm) ExecStderr(cxt context.Context, cmd string, shell string) ([]byte, error)
  • func (m *MockTerm) ExecStdout(cxt context.Context, cmd string, shell string) ([]byte, error)
• type SingleCmd
• type Target
  • func FindTarget(cp *CmdPkg, t string) (*Target, error)
• type Terminal

Functions

func LogToFile

func LogToFile(fpath string, fname string) (io.Writer, error)

LogToFile takes a path and a file name and attempts to create the path and file name as the target for the CmdPkg.Log output by returning a io.Writer to the resulting path + file. For example, sending in "./logs" and "app.log" will return a io.Writer pointing at "./logs/app.log" relative to where the Go program is run

Types

type CmdCollection

type CmdCollection struct {
	Label      string   // Holds a human friendly label for the collection
	Collection []CmdPkg // Allows commands for multiple targets to be stored together
}

TODO: Decide if this is needed Collection of multiple command packages

type CmdPkg

type CmdPkg struct {
	Label        string                 // Holds a human friendly label for the command package
	Targets      []Target               // Hold the target(s) the commands where the commands run
	Location     Terminal               // Holds the command-line interface for local or remote command invocation
	Log          map[string]*log.Logger // Holds a pointer to a Logger using Go's log module from the stadard library
	Redact       bool                   // Determine if redaction should be turned on; defaults to true
	StrRedact    []string               // List of strings to redact from logging
	CmdLog       *log.Logger            // Optional 2nd logger to write out commands and output from them
	EnableCmdLog bool                   /// Determine if commands should be logged; defaults to false
}

Holds a named package of commands for one or more targets

func NewPkg

func NewPkg(l string) *CmdPkg

Create a new empty command package with the provided label l

func (*CmdPkg) AddCmd

func (cp *CmdPkg) AddCmd(c string, e string, h bool, d time.Duration, t string) error

Add a single command to a command package target

func (*CmdPkg) AddCmdWText

func (cp *CmdPkg) AddCmdWText(c string, e string, h bool, d time.Duration, t string, b string, a string) error

Add a single command to a command package target

func (*CmdPkg) AddRedact

func (cp *CmdPkg) AddRedact(s string)

Add a single item to the list of items to redact from log messages

func (*CmdPkg) AddRedactSlice

func (cp *CmdPkg) AddRedactSlice(s []string)

Add a slice of strings to the list of items to redact from logs messages

func (*CmdPkg) AddTarget

func (cp *CmdPkg) AddTarget(id string, dist string, rel string, os string, sh string)

Set the target for the collection of commands

func (*CmdPkg) ExecPkgCombined

func (cp *CmdPkg) ExecPkgCombined(t string) ([]byte, error)

Execute the commands for the provided target t returning a slice of bytes representing stdout and stderr combined for the commands run. An error is returned if the target isn't found in the command package or an error occurs during running the commands.

func (*CmdPkg) ExecPkgError

func (cp *CmdPkg) ExecPkgError(t string) error

Execute the commands for the provided target t returning only a Go error if the target isn't found in the command package or an error occurs during running the commands. Stdout and Stderr are silently dropped.

func (*CmdPkg) ExecPkgOnly

func (cp *CmdPkg) ExecPkgOnly(t string) error

Execute the commands for the provided target t returning only a Go error if the target isn't found in the command package. Stdout and Stderr are silently dropped.

func (*CmdPkg) ExecPkgStderr

func (cp *CmdPkg) ExecPkgStderr(t string) ([]byte, error)

Execute the commands for the provided target t returning a slice of bytes representing only stdout for the commands run. An error is returned if the target isn't found in the command package or an error occurs during running the commands.

func (*CmdPkg) ExecPkgStdout

func (cp *CmdPkg) ExecPkgStdout(t string) ([]byte, error)

Execute the commands for the provided target t returning a slice of bytes representing only stdout for the commands run. An error is returned if the target isn't found in the command package or an error occurs during running the commands.

func (*CmdPkg) LoadCmds

func (cp *CmdPkg) LoadCmds(c []SingleCmd, t string) error

Add a slice of SingleCmd to a command package target

func (*CmdPkg) LogCmd

func (cp *CmdPkg) LogCmd(msg string)

Write a error level message to the configured logger

func (*CmdPkg) LogError

func (cp *CmdPkg) LogError(msg string)

Write a error level message to the configured logger

func (*CmdPkg) LogInfo

func (cp *CmdPkg) LogInfo(msg string)

Write a info level message to the configured logger

func (*CmdPkg) LogTrace

func (cp *CmdPkg) LogTrace(msg string)

Write a trace level message to the configured logger

func (*CmdPkg) LogWarn

func (cp *CmdPkg) LogWarn(msg string)

Write a warning level message to the configured logger

func (*CmdPkg) Redactatron

func (cp *CmdPkg) Redactatron(l string) string

Redactatron - redacts sensitive information from being written to the logs Redaction is configurable with Install's Redact boolean config. If true (the default), sensitive info will be redacted

func (*CmdPkg) SetCmdLog

func (cp *CmdPkg) SetCmdLog(logHandler io.Writer)

func (*CmdPkg) SetLocation

func (cp *CmdPkg) SetLocation(cl Terminal)

Set the Location - either local aka on the host or remote aka over SSH

func (*CmdPkg) SetLogging

func (cp *CmdPkg) SetLogging(logHandler io.Writer)

SetLogging takes an io.Writer and creates new log.loggers for the following logging levels: trace, info, warning, error. All log levels will be written to the same io.Writer with the level prepended to the log line.

func (*CmdPkg) TurnOffRedaction

func (cp *CmdPkg) TurnOffRedaction()

Turn off redacting of log messages

func (*CmdPkg) TurnOnCmdLog

func (cp *CmdPkg) TurnOnCmdLog()

Turn on logging of commands, assumes you have properly configured CmdLog

type LocalTerm

type LocalTerm struct {
}

func (*LocalTerm) ExecCombined

func (l *LocalTerm) ExecCombined(ctx context.Context, cmd string, shell string) ([]byte, error)

Exec the provided command and return the combined output (stdout and stderr) along with an error

func (*LocalTerm) ExecError

func (l *LocalTerm) ExecError(ctx context.Context, cmd string, shell string) error

Exec the provided command and return only a Go error if any occurs. Command output will be silently dropped

func (*LocalTerm) ExecOnly

func (i *LocalTerm) ExecOnly(ctx context.Context, cmd string, shell string)

Exec the provided command returning nothing. Command output and errors will be silently dropped

func (*LocalTerm) ExecStderr

func (l *LocalTerm) ExecStderr(ctx context.Context, cmd string, shell string) ([]byte, error)

Exec the provided command and return only the contents of stderr. Any output to stdout will be silently dropped

func (*LocalTerm) ExecStdout

func (l *LocalTerm) ExecStdout(ctx context.Context, cmd string, shell string) ([]byte, error)

Exec the provided command and return only the contents of stdout. Any output to stderr will be silently dropped

type MockTerm

type MockTerm struct {
	Out         []byte
	Err         error
	LastCommand string
}

func (*MockTerm) ExecCombined

func (m *MockTerm) ExecCombined(cxt context.Context, cmd string, shell string) ([]byte, error)

func (*MockTerm) ExecError

func (m *MockTerm) ExecError(ctx context.Context, cmd string, shell string) error

func (*MockTerm) ExecOnly

func (m *MockTerm) ExecOnly(ctx context.Context, cmd string, shell string)

func (*MockTerm) ExecStderr

func (m *MockTerm) ExecStderr(cxt context.Context, cmd string, shell string) ([]byte, error)

func (*MockTerm) ExecStdout

func (m *MockTerm) ExecStdout(cxt context.Context, cmd string, shell string) ([]byte, error)

type SingleCmd

type SingleCmd struct {
	Cmd        string        // Holds the command to be executed
	Errmsg     string        // Holds a custom error message to return on error
	Hard       bool          // Exit running if an error occurs during execution e.g. os.Exit(1)
	Timeout    time.Duration // Holds the max time a command can run before being cancelled
	BeforeText string        // Holds the optional text to print before starting the command
	AfterText  string        // Holds the optional text to print after starting the command
	Stdout     string        // Holds stdout from running the command
	Stderr     string        // Holds stderr from running the command
	StdBoth    string        // Holds both stdout and stderr from running the command
}

Holds a single command including the max exec time aka Timeout

type Target

type Target struct {
	ID      string      // Holds the supported Distro ID e.g. Ubuntu:21.10
	Distro  string      // Holds the supported Distro name e.g. Ubuntu
	Release string      // Holds the supported Release e.g. 21.10
	OS      string      // Holds the supported operating system e.g. Linux
	Shell   string      // Holds the supported shell to run the command in e.g. bash or sh
	PkgCmds []SingleCmd // Holds the commands in this command package
}

Targets are the targets a program using commandeer supports

func FindTarget

func FindTarget(cp *CmdPkg, t string) (*Target, error)

Look for the provided target t in a command package and either return a pointer to the Target struct or an error if the target cannot be found

type Terminal

type Terminal interface {
	ExecCombined(ctx context.Context, cmd string, shell string) ([]byte, error)
	ExecError(ctx context.Context, cmd string, shell string) error
	ExecOnly(ctx context.Context, cmd string, shell string)
	ExecStdout(ctx context.Context, cmd string, shell string) ([]byte, error)
	ExecStderr(ctx context.Context, cmd string, shell string) ([]byte, error)
}

CmdLine is an interface for running OS commands either locally or remote