// Package subcmd provides a simple and flexible subcommand framework built on // top of the standard library's [flag] package. // // This package makes it easy to build command-line applications with multiple // subcommands, similar to tools like git, docker, or kubectl. Each subcommand // can have its own flags and logic while sharing common top-level flags. // // # Basic Usage // // To use subcmd, implement the [subcmd.Command] interface for each subcommand and // [subcmd.Register] them. The library handles parsing, flag management, and command // execution. // // package main // // import ( // "context" // "flag" // "fmt" // "git.eugenetriguba.com/subcmd" // "os" // ) // // type greetCmd struct { // name string // } // // func (g *greetCmd) Name() string { return "greet" } // func (g *greetCmd) Synopsis() string { return "greet a person" } // func (g *greetCmd) Usage() string { // return `greet -name : // Prints a greeting message. // ` // } // func (g *greetCmd) SetFlags(f *flag.FlagSet) { // f.StringVar(&g.name, "name", "World", "name to greet") // } // func (g *greetCmd) Execute(ctx context.Context, f *flag.FlagSet, args ...any) subcmd.ExitStatus { // fmt.Printf("Hello, %s!\n", g.name) // return subcmd.ExitSuccess // } // // func main() { // subcmd.Register(&greetCmd{}, "") // subcmd.Register(subcmd.HelpCommand(), "") // os.Exit(int(subcmd.Execute(context.Background()))) // } // // We'll see the following output when we run our new CLI: // // $ go build -o main // $ ./main // Usage: ./main // // Subcommands: // greet greet a person // help describe subcommands and their syntax // // $ ./main help greet // greet -name : // Prints a greeting message. // // $ ./main greet -name eugene // Hello, eugene! // // # Command Groups // // Commands can be organized into groups for better help output: // // subcmd.Register(&listCmd{}, "Database Commands") // subcmd.Register(&migrateCmd{}, "Database Commands") // subcmd.Register(&statusCmd{}, "Utility Commands") // // # Built-in Commands // // The package provides several built-in commands: // // - [subcmd.HelpCommand] // - [subcmd.ManHelpCommand] // - [subcmd.CommandsCommand] // - [subcmd.FlagsCommand] // // # Registry // // Many top-level functions, like [subcmd.Register], operate on a // global default package-level registry. This makes it easier to // use the library in the common case. // // However, you can create custom registries for more control: // // registry := subcmd.NewRegistry(subcmd.WithOutput(customWriter)) // registry.Register(&myCmd{}, "") // status := registry.Execute(ctx) // // This is useful for testing or when building applications that need multiple // independent command sets. // // # Top-level Flags // // To add top-level flags (flags that apply before the subcommand), use the // [subcmd.Flags] accessor: // // verbose := subcmd.Flags().Bool("v", false, "verbose output") // subcmd.Register(&myCmd{}, "") // os.Exit(int(subcmd.Execute(context.Background()))) package subcmd