1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
// 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 [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
// }
//
// 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() {
// subcmd.Register(&greetCmd{}, "")
// subcmd.Register(subcmd.HelpCommand(), "")
// 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:
//
// 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:
//
// - [subcmd.HelpCommand]
// - [subcmd.ManHelpCommand]
// - [subcmd.CommandsCommand]
// - [subcmd.FlagsCommand]
//
// # Registry
//
// 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{}, "")
// status := registry.Execute(ctx)
//
// This is useful for testing or when building applications that need multiple
// independent command sets.
//
// # Top-level Flags
//
// To add top-level flags (flags that apply before the subcommand), use the
// [subcmd.Flags] accessor:
//
// verbose := subcmd.Flags().Bool("v", false, "verbose output")
// subcmd.Register(&myCmd{}, "")
// os.Exit(int(subcmd.Execute(context.Background())))
package subcmd
|