owl

README

Owl - Only Write (your) Logic

Owl is a micro-framework that builds on top of thethe excellent go-arg and testify libraries to allow developers to write their CLI tools in Golang, instead of maintaining brittle Bash / Python scripts.

All engineering teams will accumulate an (official or unofficial) collection of scripts to automate dev and ops tasks. Eventually, an outage will happen because of bad error handling, or a subtle bug that a static typing system would have caught. The goal of this project is to allow teams to maintain "scripts" as a Go project:

• borrowing from Busybox, all commands are compiled in a single binary for easy distribution
• input and current state can be checked with testify/require before running commands. No need to google for the bash test syntax anymore!
• common actions are more concise thanks to helpers in the must package
• commands can be extensively unit-tested, with a mocked owl allowing to intercept and mock calls to external commands
• you can leverage all the power of the standard library, and any Go library you already work with

How to use it

Minimal example

// rootCommand holds the list of active commands, and embeds owl.Base for common helpers.
type rootCommand struct {
    owl.Base
    Lower   *lowerCmd `arg:"subcommand:lower" help:"return the text in lowercase"`
}

// lowerCmd holds the arguments for this command.
type lowerCmd struct {
    Text string `arg:"positional" help:"text to lowercase"`
}

// Run is the entrypoint for your command, argument values are set in the struct fields.
func (c *lowerCmd) Run(o owl.Owl) {
    out := strings.ToLower(c.Text)
    require.NotEqual(o, "viper", out, "snakes not allowed here")
    o.Println(out)
}

// main just calls owl.RunOwl to parse arguments and start the selected command.
func main() {
    owl.RunOwl(new(rootCommand))
}

Going further

• Checkout the examples folder to explore the available features
• Read the go-arg readme and reference documentation for available argument types
• Read the owl reference documentation for available helpers

Documentation

Index

• func RunOwl(root Owl)
• type Base
  • func (o *Base) Errorf(format string, args ...interface{})
  • func (o *Base) ExecCommand(name string, arg ...string) *exec.Cmd
  • func (o *Base) FailNow()
  • func (o *Base) IsVerbose() bool
  • func (o *Base) Printf(format string, a ...interface{})
  • func (o *Base) Println(a ...interface{})
• type Owl
• type ShellAliases

Functions

func RunOwl

func RunOwl(root Owl)

RunOwl is the entrypoint to call with your root struct. The arguments will be parsed and the relevant command called.

Types

type Base

type Base struct {
	Verbose bool `arg:"-v" help:"display full errors"`
	// contains filtered or unexported fields
}

Base provides the base logic to detect and run commands. It must be embedded in your root command struct.

func (*Base) Errorf

func (o *Base) Errorf(format string, args ...interface{})

Errorf is provided for compatibility with testify/require, it will print the errors to stderr. Unless verbose is set, testify messages are detected and shortened to the message line only.

func (*Base) ExecCommand

func (o *Base) ExecCommand(name string, arg ...string) *exec.Cmd

ExecCommand wraps exec.Command, to enable mocking during unit tests

func (*Base) FailNow

func (o *Base) FailNow()

FailNow is provided for compatibility with testify/require, a panic will trigger an exit with code 1

func (*Base) IsVerbose

func (o *Base) IsVerbose() bool

IsVerbose returns true if the `--verbose` flag has been given.

func (*Base) Printf

func (o *Base) Printf(format string, a ...interface{})

Printf wraps fnt.Printf to a configurable stdout, to enable unit testing

func (*Base) Println

func (o *Base) Println(a ...interface{})

Println wraps fnt.Println to a configurable stdout, to enable unit testing

type Owl

type Owl interface {
	Errorf(format string, args ...interface{})
	ExecCommand(name string, arg ...string) *exec.Cmd
	FailNow()
	IsVerbose() bool
	Printf(format string, a ...interface{})
	Println(a ...interface{})
}

Owl provides helpers for your commands, see Base for documentation. Commands can cast it to your root type to access global options.

type ShellAliases

type ShellAliases struct {
	ShellAliases *shellAliasesCmd `arg:"subcommand:build-shell-aliases" help:"generate shell aliases for all subcommands"`
}

ShellAliases registers a build-shell-aliases subcommand that auto-generates shell aliases for all active subcommands.