From ec47c447fe112f3aa3e8b42c914f0bdc2a649e7e Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Mon, 13 Oct 2025 09:38:18 -0400 Subject: Initial Commit --- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..e2b565b --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# subcmd + +[![GoDoc](https://godoc.org/git.sr.ht/~eugenetriguba/subcmd?status.svg)](https://godoc.org/git.sr.ht/~eugenetriguba/subcmd) +![Version](https://img.shields.io/badge/version-0.1.0-blue) +[![Build Status](https://builds.sr.ht/~eugenetriguba/subcmd/commits/main.svg)](https://builds.sr.ht/~eugenetriguba/subcmd/commits/main?) + +A simple and flexible subcommand framework for Go, built on top of the standard library's `flag` package. + +## Why subcmd? + +- **Simple** - Small 5-method interface and register your commands +- **Familiar** - Built on `flag.FlagSet` +- **Flexible** - Command groups, custom registries, and built-in help system +- **Lightweight** - Zero external dependencies for production use +- **Testable** - Custom registries make testing easy + +## Installation + +```bash +go get git.sr.ht/~eugenetriguba/subcmd +``` + +## Example + +```go +package main + +import ( + "context" + "flag" + "fmt" + "os" + + "git.sr.ht/~eugenetriguba/subcmd" +) + +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" } + +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(), "") + flag.Parse() + os.Exit(int(subcmd.Execute(context.Background()))) +} +``` + +```bash +$ go run main.go greet -name Alice +Hello, Alice! +``` + +## Documentation + +See the [GoDoc documentation](https://godoc.org/git.sr.ht/~eugenetriguba/subcmd) +for full documentation on: + +- Command interface implementation +- Organizing commands into groups +- Built-in commands (help, commands, flags) +- Custom registries for testing +- Advanced usage patterns + +## License + +See [LICENSE](./LICENSE) file for details. -- cgit v1.2.3