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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ¶
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 ¶ added in v0.2.0
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
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 ¶ added in v0.2.0
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.
Source Files
Directories