Simple, intuitive CLI framework for Go
pkg.go.dev/go.followtheprocess.codes/cli
go
cli
Tidy up some doc comments (#135)
+38
-40
+34
-35
command.go
+34
-35
command.go
···
188
188
//
189
189
// If the flags fail to parse, an error will be returned and the Run function
190
190
// will not be called.
191
-
func (c *Command) Execute() error {
192
-
if c == nil {
191
+
func (cmd *Command) Execute() error {
192
+
if cmd == nil {
193
193
return errors.New("Execute called on a nil Command")
194
194
}
195
195
196
196
// Regardless of where we call execute, run it only from the root command, this is to ensure
197
197
// that when we use the arguments to go and find the subcommand to run (if needed), then we
198
198
// at the root of the command tree.
199
-
if c.parent != nil {
200
-
return fmt.Errorf("Execute must be called on the root of the command tree, was called on %s", c.name)
199
+
if cmd.parent != nil {
200
+
return fmt.Errorf("Execute must be called on the root of the command tree, was called on %s", cmd.name)
201
201
}
202
202
203
203
// Use the raw arguments and the command tree to determine which subcommand (if any)
204
-
// we should be invoking. If it turns out we want to invoke the root command, then
205
-
// cmd here will be c.
206
-
cmd, args := findRequestedCommand(c, c.args)
207
-
208
-
// Below this point, use cmd not c!
204
+
// we should be invoking and swap that into 'cmd'.
205
+
//
206
+
// Slightly magical trick but it simplifies a lot of stuff below.
207
+
cmd, args := findRequestedCommand(cmd, cmd.args)
209
208
210
209
if err := cmd.flagSet().Parse(args); err != nil {
211
210
return fmt.Errorf("failed to parse command flags: %w", err)
···
240
239
return errors.New("versionFunc was nil")
241
240
}
242
241
243
-
if err := cmd.versionFunc(c); err != nil {
242
+
if err := cmd.versionFunc(cmd); err != nil {
244
243
return fmt.Errorf("version function returned an error: %w", err)
245
244
}
246
245
···
293
292
}
294
293
295
294
// Flags returns the set of flags for the command.
296
-
func (c *Command) flagSet() *flag.Set {
297
-
if c == nil {
295
+
func (cmd *Command) flagSet() *flag.Set {
296
+
if cmd == nil {
298
297
// Only thing to do really, slightly more helpful than a generic
299
298
// nil pointer dereference
300
299
panic("flagSet called on a nil Command")
301
300
}
302
301
303
-
if c.flags == nil {
302
+
if cmd.flags == nil {
304
303
return flag.NewSet()
305
304
}
306
305
307
-
return c.flags
306
+
return cmd.flags
308
307
}
309
308
310
309
// Stdout returns the configured Stdout for the Command.
311
-
func (c *Command) Stdout() io.Writer {
312
-
return c.root().stdout
310
+
func (cmd *Command) Stdout() io.Writer {
311
+
return cmd.root().stdout
313
312
}
314
313
315
314
// Stderr returns the configured Stderr for the Command.
316
-
func (c *Command) Stderr() io.Writer {
317
-
return c.root().stderr
315
+
func (cmd *Command) Stderr() io.Writer {
316
+
return cmd.root().stderr
318
317
}
319
318
320
319
// Stdin returns the configured Stdin for the Command.
321
-
func (c *Command) Stdin() io.Reader {
322
-
return c.root().stdin
320
+
func (cmd *Command) Stdin() io.Reader {
321
+
return cmd.root().stdin
323
322
}
324
323
325
324
// Arg looks up a named positional argument by name.
···
328
327
// then the value returned will be the default value.
329
328
//
330
329
// If no named argument exists with the given name, it will return "".
331
-
func (c *Command) Arg(name string) string {
332
-
for _, arg := range c.positionalArgs {
330
+
func (cmd *Command) Arg(name string) string {
331
+
for _, arg := range cmd.positionalArgs {
333
332
if arg.name == name {
334
333
// arg.value will have been set to the default already during command line parsing
335
334
// if the arg was not provided
···
345
344
// pass through in your commands.
346
345
//
347
346
// If there were no extra arguments, it will return nil, false.
348
-
func (c *Command) ExtraArgs() (args []string, ok bool) {
349
-
extra := c.flagSet().ExtraArgs()
347
+
func (cmd *Command) ExtraArgs() (args []string, ok bool) {
348
+
extra := cmd.flagSet().ExtraArgs()
350
349
if len(extra) > 0 {
351
350
return extra, true
352
351
}
···
355
354
}
356
355
357
356
// root returns the root of the command tree.
358
-
func (c *Command) root() *Command {
359
-
if c.parent != nil {
360
-
return c.parent.root()
357
+
func (cmd *Command) root() *Command {
358
+
if cmd.parent != nil {
359
+
return cmd.parent.root()
361
360
}
362
361
363
-
return c
362
+
return cmd
364
363
}
365
364
366
365
// hasFlag returns whether the command has a flag of the given name defined.
367
-
func (c *Command) hasFlag(name string) bool {
368
-
flag, ok := c.flagSet().Get(name)
366
+
func (cmd *Command) hasFlag(name string) bool {
367
+
flag, ok := cmd.flagSet().Get(name)
369
368
if !ok {
370
369
return false
371
370
}
···
374
373
}
375
374
376
375
// hasShortFlag returns whether the command has a shorthand flag of the given name defined.
377
-
func (c *Command) hasShortFlag(name string) bool {
376
+
func (cmd *Command) hasShortFlag(name string) bool {
378
377
if name == "" {
379
378
return false
380
379
}
381
380
382
381
char, _ := utf8.DecodeRuneInString(name)
383
382
384
-
flag, ok := c.flagSet().GetShort(char)
383
+
flag, ok := cmd.flagSet().GetShort(char)
385
384
if !ok {
386
385
return false
387
386
}
···
390
389
}
391
390
392
391
// subcommandNames returns a list of all the names of the current command's registered subcommands.
393
-
func (c *Command) subcommandNames() []string {
394
-
names := make([]string, 0, len(c.subcommands))
395
-
for _, sub := range c.subcommands {
392
+
func (cmd *Command) subcommandNames() []string {
393
+
names := make([]string, 0, len(cmd.subcommands))
394
+
for _, sub := range cmd.subcommands {
396
395
names = append(names, sub.name)
397
396
}
398
397
+4
-5
option.go
+4
-5
option.go
···
16
16
const NoShortHand = flag.NoShortHand
17
17
18
18
// Flaggable is a type constraint that defines any type capable of being parsed as a command line flag.
19
-
//
20
-
// It's worth noting that the complete set of supported types is wider than this constraint appears
21
-
// as e.g. a [time.Duration] is actually just an int64 underneath, likewise a [net.IP] is actually just []byte.
22
19
type Flaggable flag.Flaggable
23
20
24
21
// Note: this must be a type alias (FlagCount = flag.Count), not a newtype (FlagCount flag.Count)
···
75
72
versionCalled bool
76
73
}
77
74
78
-
// build builds an returns a Command from the config, applying validation
79
-
// to the whole thing.
75
+
// build builds an returns a Command from the config.
76
+
//
77
+
// The returned command is a completely standalone CLI program with no back-references
78
+
// to the config, so is effectively immutable to the user.
80
79
func (c *config) build() *Command {
81
80
cmd := &Command{
82
81
stdin: c.stdin,