README
¶
__ ____
____ _ / // __/
/ __ `// // /_
/ /_/ // // __/
\__,_//_//_/
alf is a simple toolset for making command line applications in golang. Some
design goals include:
- helping you organize a command line application so its maintainable.
- minimize dependencies.
- written examples, tests to demonstrate how to use it.
This library is nothing but a thin wrapper around the the very awesome and
stable standard library package, flag. See
the tests for an idea of how to use this library. Check out the examples for
comments and a quick exploratory demo.
go run ./examples/full
overview
There's two basic types, Delegator and Command. A Delegator is a parent of
a set of commands. A Command does the work. Both are abstracted as
Directive.
Your program should have a Root, which is just a Delegator with a Run
method. From your package main, commence Run like so:
err = root.Run(context.Background(), os.Args[1:])
limitations
Currently it does not permit sharing flag values from a Root to a direct child
command. However, you could share flag values between a Delegator (one that's
not a Root command) and child commands.
Documentation
¶
Overview ¶
Package alf is a small, no-frills toolset for creating simple command line applications. It's a thin wrapper around the standard library's flag package with some stuff to make composition and documentation generation easier. See the examples directory for demo usage.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrShowUsage = errors.New("")
ErrShowUsage should be returned or wrapped when you want to show the command's help menu (run its Usage func) even though the user did not specifically request it. It has no text so it doesn't mess up your error message if you're use error wrapping.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
// Description should provide a short summary.
Description string
// Setup is passed the parent flag set and returns a flag set. Call the
// (*flag.FlagSet).Init method to reuse the parent flags and modify it as
// needed. You could also just allow the input flagset to pass through. If
// you don't want to share any flag data between parent and child, then
// create a new flag set.
Setup func(parentFlags flag.FlagSet) *flag.FlagSet
// Run is a wrapper function that selects the necessary command line inputs,
// executes the command and returns any errors.
Run func(ctx context.Context) error
// contains filtered or unexported fields
}
A Command performs a task. A parent Delegator passes control to one of these.
type Delegator ¶
type Delegator struct {
// Description should provide a short summary.
Description string
// Flags collect and share inputs to its sub directives.
Flags *flag.FlagSet
// Selected is the chosen transfer point of control.
Selected Directive
// Subs associates a name with another Directive. The name is what to
// specify from the command line.
Subs map[string]Directive
}
A Delegator is a parent to a set of commands. Its sole purpose is to direct traffic to a selected command. It can also collect common flag inputs to pass on to subcommands.
func (*Delegator) DescribeSubcommands ¶
DescribeSubcommands outputs summaries of each subcommand ordered by name.
type Directive ¶
type Directive interface {
// Summary provides a short, one-line description.
Summary() string
// Perform should either choose a subcommand or do a task.
Perform(ctx context.Context) error
}
Directive is an abstraction for a parent or child command. A parent would delegate to a subcommand, while a subcommand does the actual task.
type Root ¶
type Root struct {
*Delegator
// PrePerform is an optional function to invoke during Run, after the flags
// have been parsed but before a subcommand is chosen. Run will return early
// if this function returns an error.
PrePerform func(ctx context.Context) error
}
Root is your main, top-level command.
Source Files
Directories