diff options
| author | Eugene Triguba <hello@eugenetriguba.com> | 2025-12-27 18:26:05 -0500 |
|---|---|---|
| committer | Eugene Triguba <hello@eugenetriguba.com> | 2025-12-27 18:26:05 -0500 |
| commit | b8b9d64012f07a48cf97394805a3368287ff41f2 (patch) | |
| tree | 8c5b94657e7f58366f93dfda5c4b79de487ed6a3 /doc.go | |
| parent | Release v0.5.0 (diff) | |
| download | subcmd-b8b9d64012f07a48cf97394805a3368287ff41f2.zip | |
Clarify godoc comments and provide more examples
Diffstat (limited to 'doc.go')
| -rw-r--r-- | doc.go | 54 |
1 files changed, 41 insertions, 13 deletions
@@ -1,5 +1,5 @@ // Package subcmd provides a simple and flexible subcommand framework built on -// top of the standard library's flag package. +// 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 @@ -7,9 +7,19 @@ // // # 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. +// To use subcmd, implement the [subcmd.Command] interface for each subcommand and +// [subcmd.Register] them. The library handles parsing, flag management, and command +// execution. +// +// package main +// +// import ( +// "context" +// "flag" +// "fmt" +// "git.sr.ht/~eugenetriguba/subcmd" +// "os" +// ) // // type greetCmd struct { // name string @@ -22,11 +32,9 @@ // 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 @@ -38,6 +46,23 @@ // os.Exit(int(subcmd.Execute(context.Background()))) // } // +// We'll see the following output when we run our new CLI: +// +// $ go build -o main +// $ ./main +// Usage: ./main <flags> <subcommand> <subcommand args> +// +// Subcommands: +// greet greet a person +// help describe subcommands and their syntax +// +// $ ./main help greet +// greet -name <name>: +// Prints a greeting message. +// +// $ ./main greet -name eugene +// Hello, eugene! +// // # Command Groups // // Commands can be organized into groups for better help output: @@ -50,15 +75,18 @@ // // The package provides several built-in commands: // -// - HelpCommand() - Display help for all commands or a specific command -// - ManHelpCommand(prefix) - Open man pages for commands (e.g., "myapp" and "myapp-subcommand") -// - CommandsCommand() - List all available command names -// - FlagsCommand() - List all top-level flags +// - [subcmd.HelpCommand] +// - [subcmd.ManHelpCommand] +// - [subcmd.CommandsCommand] +// - [subcmd.FlagsCommand] // // # Registry // -// While the package provides a default registry for convenience, you can -// create custom registries for more control: +// Many top-level functions, like [subcmd.Register], operate on a +// global default package-level registry. This makes it easier to +// use the library in the common case. +// +// However, you can create custom registries for more control: // // registry := subcmd.NewRegistry(subcmd.WithOutput(customWriter)) // registry.Register(&myCmd{}, "") @@ -70,7 +98,7 @@ // # Top-level Flags // // To add top-level flags (flags that apply before the subcommand), use the -// Flags() accessor: +// [subcmd.Flags] accessor: // // verbose := subcmd.Flags().Bool("v", false, "verbose output") // subcmd.Register(&myCmd{}, "") |