tool

Documentation

Overview

Package tool is an opinionated harness for writing Go tools.

Index

• func CommandLineErrorf(message string, args ...interface{}) error
• func Main(ctx context.Context, app Application, args []string)
• func Run(ctx context.Context, app Application, args []string) error
• type Application
• type Profile

Functions

func CommandLineErrorf

func CommandLineErrorf(message string, args ...interface{}) error

CommandLineErrorf is like fmt.Errorf except that it returns a value that triggers printing of the command line help. In general you should use this when generating command line validation errors.

func Main

func Main(ctx context.Context, app Application, args []string)

Main should be invoked directly by main function. It will only return if there was no error. If an error was encountered it is printed to standard error and the application exits with an exit code of 2.

func Run

func Run(ctx context.Context, app Application, args []string) error

Run is the inner loop for Main; invoked by Main, recursively by Run, and by various tests. It runs the application and returns an error.

Types

type Application

type Application interface {
	// Name returns the application's name. It is used in help and error messages.
	Name() string
	// Most of the help usage is automatically generated, this string should only
	// describe the contents of non flag arguments.
	Usage() string
	// ShortHelp returns the one line overview of the command.
	ShortHelp() string
	// DetailedHelp should print a detailed help message. It will only ever be shown
	// when the ShortHelp is also printed, so there is no need to duplicate
	// anything from there.
	// It is passed the flag set so it can print the default values of the flags.
	// It should use the flag sets configured Output to write the help to.
	DetailedHelp(*flag.FlagSet)
	// Run is invoked after all flag processing, and inside the profiling and
	// error handling harness.
	Run(ctx context.Context, args ...string) error
}

Application is the interface that must be satisfied by an object passed to Main.

type Profile

type Profile struct {
	CPU    string `flag:"profile.cpu" help:"write CPU profile to this file"`
	Memory string `flag:"profile.mem" help:"write memory profile to this file"`
	Trace  string `flag:"profile.trace" help:"write trace log to this file"`
}

Profile can be embedded in your application struct to automatically add command line arguments and handling for the common profiling methods.