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 /README.md | |
| download | subcmd-ec47c447fe112f3aa3e8b42c914f0bdc2a649e7e.zip | |
Initial Commit
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 80 |
1 files changed, 80 insertions, 0 deletions
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 + +[](https://godoc.org/git.sr.ht/~eugenetriguba/subcmd) + +[](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 <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. |