aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
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 /README.md
downloadsubcmd-ec47c447fe112f3aa3e8b42c914f0bdc2a649e7e.zip
Initial Commit
Diffstat (limited to 'README.md')
-rw-r--r--README.md80
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
+
+[![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 <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.