From ec47c447fe112f3aa3e8b42c914f0bdc2a649e7e Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Mon, 13 Oct 2025 09:38:18 -0400 Subject: Initial Commit --- doc.go | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 doc.go (limited to 'doc.go') diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..9371bdb --- /dev/null +++ b/doc.go @@ -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 : +// 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 -- cgit v1.2.3