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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
# ffcli [](https://pkg.go.dev/github.com/peterbourgon/ff/v3/ffcli)
ffcli stands for flags-first command line interface,
and provides an opinionated way to build CLIs.
## Rationale
Popular CLI frameworks like [spf13/cobra][cobra], [urfave/cli][urfave], or
[alecthomas/kingpin][kingpin] tend to have extremely large APIs, to support a
large number of "table stakes" features.
[cobra]: https://github.com/spf13/cobra
[urfave]: https://github.com/urfave/cli
[kingpin]: https://github.com/alecthomas/kingpin
This package is intended to be a lightweight alternative to those packages. In
contrast to them, the API surface area of package ffcli is very small, with the
immediate goal of being intuitive and productive, and the long-term goal of
supporting commandline applications that are substantially easier to understand
and maintain.
To support these goals, the package is concerned only with the core mechanics of
defining a command tree, parsing flags, and selecting a command to run. It does
not intend to be a one-stop-shop for everything your commandline application
needs. Features like tab completion or colorized output are orthogonal to
command tree parsing, and should be easy to provide on top of ffcli.
Finally, this package follows in the philosophy of its parent package ff, or
"flags-first". Flags, and more specifically the Go stdlib flag.FlagSet, should
be the primary mechanism of getting configuration from the execution environment
into your program. The affordances provided by package ff, including environment
variable and config file parsing, are also available in package ffcli. Support
for other flag packages is a non-goal.
## Goals
- Absolute minimum usable API
- Prefer using existing language features/patterns/abstractions whenever possible
- Enable integration-style testing of CLIs with mockable dependencies
- No global state
## Non-goals
- All conceivably useful features
- Integration with flag packages other than [package flag][flag] and [ff][ff]
[flag]: https://golang.org/pkg/flag
[ff]: https://github.com/peterbourgon/ff
## Usage
The core of the package is the [ffcli.Command][command]. Here is the simplest
possible example of an ffcli program.
[command]: https://godoc.org/github.com/peterbourgon/ff/ffcli#Command
```go
import (
"context"
"os"
"github.com/peterbourgon/ff/v3/ffcli"
)
func main() {
root := &ffcli.Command{
Exec: func(ctx context.Context, args []string) error {
println("hello world")
return nil
},
}
root.ParseAndRun(context.Background(), os.Args[1:])
}
```
Most CLIs use flags and arguments to control behavior. Here is a command which
takes a string to repeat as an argument, and the number of times to repeat it as
a flag.
```go
fs := flag.NewFlagSet("repeat", flag.ExitOnError)
n := fs.Int("n", 3, "how many times to repeat")
root := &ffcli.Command{
ShortUsage: "repeat [-n times] <arg>",
ShortHelp: "Repeatedly print the argument to stdout.",
FlagSet: fs,
Exec: func(ctx context.Context, args []string) error {
if nargs := len(args); nargs != 1 {
return fmt.Errorf("repeat requires exactly 1 argument, but you provided %d", nargs)
}
for i := 0; i < *n; i++ {
fmt.Fprintln(os.Stdout, args[0])
}
return nil
},
}
if err := root.ParseAndRun(context.Background(), os.Args[1:]); err != nil {
log.Fatal(err)
}
```
Each command may have subcommands, allowing you to build a command tree.
```go
var (
rootFlagSet = flag.NewFlagSet("textctl", flag.ExitOnError)
verbose = rootFlagSet.Bool("v", false, "increase log verbosity")
repeatFlagSet = flag.NewFlagSet("textctl repeat", flag.ExitOnError)
n = repeatFlagSet.Int("n", 3, "how many times to repeat")
)
repeat := &ffcli.Command{
Name: "repeat",
ShortUsage: "textctl repeat [-n times] <arg>",
ShortHelp: "Repeatedly print the argument to stdout.",
FlagSet: repeatFlagSet,
Exec: func(_ context.Context, args []string) error { ... },
}
count := &ffcli.Command{
Name: "count",
ShortUsage: "textctl count [<arg> ...]",
ShortHelp: "Count the number of bytes in the arguments.",
Exec: func(_ context.Context, args []string) error { ... },
}
root := &ffcli.Command{
ShortUsage: "textctl [flags] <subcommand>",
FlagSet: rootFlagSet,
Subcommands: []*ffcli.Command{repeat, count},
}
if err := root.ParseAndRun(context.Background(), os.Args[1:]); err != nil {
log.Fatal(err)
}
```
ParseAndRun can also be split into distinct Parse and Run phases, allowing you
to perform two-phase setup or initialization of e.g. API clients that require
user-supplied configuration.
## Examples
See [the examples directory][examples]. If you'd like an example of a specific
type of program structure, or a CLI that satisfies a specific requirement,
please [file an issue][issue].
[examples]: https://github.com/peterbourgon/ff/tree/master/ffcli/examples
[issue]: https://github.com/peterbourgon/ff/issues/new
|
