diff options
| author | Eugene Triguba <hello@eugenetriguba.com> | 2025-10-13 09:38:18 -0400 |
|---|---|---|
| committer | Eugene Triguba <hello@eugenetriguba.com> | 2025-10-13 09:38:18 -0400 |
| commit | ec47c447fe112f3aa3e8b42c914f0bdc2a649e7e (patch) | |
| tree | a85e4fba976bea69f098b7c672c883a7627a3186 /doc.go | |
| download | subcmd-ec47c447fe112f3aa3e8b42c914f0bdc2a649e7e.zip | |
Initial Commit
Diffstat (limited to 'doc.go')
| -rw-r--r-- | doc.go | 76 |
1 files changed, 76 insertions, 0 deletions
@@ -0,0 +1,76 @@ +// 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 Command interface for each subcommand and +// register them with a Registry. The framework handles parsing, flag management, +// and command execution. +// +// 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 <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() { +// // Register commands +// subcmd.Register(&greetCmd{}, "") +// subcmd.Register(subcmd.HelpCommand(), "") +// +// // Parse top-level flags +// flag.Parse() +// +// // Execute the subcommand +// ctx := context.Background() +// os.Exit(int(subcmd.Execute(ctx))) +// } +// +// # 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: +// +// - HelpCommand() - Display help for all commands or a specific command +// - CommandsCommand() - List all available command names +// - FlagsCommand() - List all top-level flags +// +// # Registry +// +// While the package provides a default registry for convenience, you can +// create custom registries for more control: +// +// registry := subcmd.NewRegistry() +// registry.Register(&myCmd{}, "") +// registry.SetOutput(customWriter) +// status := registry.Execute(ctx) +// +// This is useful for testing or when building applications that need multiple +// independent command sets. +package subcmd |