aboutsummaryrefslogtreecommitdiffstats
path: root/doc.go
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-10-13 09:38:18 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-10-13 09:38:18 -0400
commitec47c447fe112f3aa3e8b42c914f0bdc2a649e7e (patch)
treea85e4fba976bea69f098b7c672c883a7627a3186 /doc.go
downloadsubcmd-ec47c447fe112f3aa3e8b42c914f0bdc2a649e7e.zip
Initial Commit
Diffstat (limited to 'doc.go')
-rw-r--r--doc.go76
1 files changed, 76 insertions, 0 deletions
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 <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