forked from jawher/mow.cli
/
doc.go
414 lines (267 loc) · 14.9 KB
/
doc.go
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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
/*
Package cli provides a framework to build command line applications in Go with most of the burden of arguments parsing and validation
placed on the framework instead of the user.
Basics
You start by creating an application by passing a name and a description:
cp = cli.App("cp", "Copy files around")
To attach the code to execute when the app is launched, assign a function to the Action field:
cp.Action = func() {
fmt.Printf("Hello world\n")
}
Finally, in your main func, call Run on the app:
cp.Run(os.Args)
Options
To add a (global) option, call one of the (String[s]|Int[s]|Bool)Opt methods on the app:
recursive := cp.BoolOpt("R recursive", false, "recursively copy the src to dst")
* The first argument is a space separated list of names for the option without the dashes
* The second parameter is the default value for the option
* The third parameter is the option description, as will be shown in the help messages
There is also a second set of methods Bool, String, Int, Strings and Ints, which accepts structs describing the option:
recursive = cp.Bool(BoolOpt{
Name: "R",
Value: false,
Desc: "copy src files recursively",
EnvVar: "",
})
The field names are self-describing.
There EnvVar field is a space separated list of environment variables names to be used to initialize the option.
The result is a pointer to a value that will be populated after parsing the command line arguments.
You can access the values in the Action func.
In the command line, mow.cli accepts the following syntaxes
* For boolean options:
-f : a single dash for the one letter names
-f=false : a single dash for the one letter names, equal sign followed by true or false
--force : double dash for longer option names
-it : mow.cli supports option folding, this is equivalent to: -i -t
* For string, int options:
-e=value : single dash for one letter names, equal sign followed by the value
-e value : single dash for one letter names, space followed by the value
-Ivalue : single dash for one letter names immediately followed by the value
--extra=value : double dash for longer option names, equal sign followed by the value
--extra value : double dash for longer option names, space followed by the value
* For slice options (StringsOpt, IntsOpt): repeat the option to accumulate the values in the resulting slice:
-e PATH:/bin -e PATH:/usr/bin : resulting slice contains ["/bin", "/usr/bin"]
Arguments
To accept arguments, you need to explicitly declare them by calling one of the (String[s]|Int[s]|Bool)Arg methods on the app:
src := cp.StringArg("SRC", "", "the file to copy")
dst := cp.StringArg("DST", "", "the destination")
* The first argument is the argument name as will be shown in the help messages
* The second parameter is the default value for the argument
* The third parameter is the argument description, as will be shown in the help messages
There is also a second set of methods Bool, String, Int, Strings and Ints, which accepts structs describing the argument:
src = cp.Strings(StringsArg{
Name: "SRC",
Desc: "The source files to copy",
Value: "",
EnvVar: "",
})
The field names are self-describing.
The Value field is where you can set the initial value for the argument.
EnvVar accepts a space separated list of environment variables names to be used to initialize the argument.
The result is a pointer to a value that will be populated after parsing the command line arguments.
You can access the values in the Action func.
Operators
The -- operator marks the end of options.
Everything that follow will be treated as an argument,
even if starts with a dash.
For example, given the touch command which takes a filename as an argument (and possibly other options):
file := cp.StringArg("FILE", "", "the file to create")
If we try to create a file named -f this way:
touch -f
Would fail, because -f will be parsed as an option not as an argument.
The fix is to prefix the filename with the -- operator:
touch -- -f
Commands
mow.cli supports nesting commands and sub commands.
Declare a top level command by calling the Command func on the app struct, and a sub command by calling
the Command func on the command struct:
docker := cli.App("docker", "A self-sufficient runtime for linux containers")
docker.Command("run", "Run a command in a new container", func(cmd *cli.Cmd) {
// initialize the run command here
})
* The first argument is the command name, as will be shown in the help messages and as will need to be input by the user in the command line to call the command
* The second argument is the command description as will be shown in the help messages
* The third argument is a CmdInitializer, a function that receives a pointer to a Cmd struct representing the command.
In this function, you can add options and arguments by calling the same methods as you would with an app struct (BoolOpt, StringArg, ...).
You would also assign a function to the Action field of the Cmd struct for it to be executed when the command is invoked.
docker.Command("run", "Run a command in a new container", func(cmd *cli.Cmd) {
detached := cmd.BoolOpt("d detach", false, "Detached mode: run the container in the background and print the new container ID")
memory := cmd.StringOpt("m memory", "", "Memory limit (format: <number><optional unit>, where unit = b, k, m or g)")
image := cmd.StringArg("IMAGE", "", "The image to run")
cmd.Action = func() {
if *detached {
//do something
}
runContainer(*image, *detached, *memory)
}
})
You can also add sub commands by calling Command on the Cmd struct:
bzk.Command("job", "actions on jobs", func(cmd *cli.Cmd) {
cmd.Command("list", "list jobs", listJobs)
cmd.Command("start", "start a new job", startJob)
cmd.Command("log", "show a job log", nil)
})
This could go on to any depth if need be.
As a side-note: it may seem a bit weird the way mow.cli uses a function to initialize a command
instead of just returning the command struct.
The motivation behind this choice is scoping: as with the standard flag package, adding an option or an argument
returns a pointer to a value which will be populated when the app is run.
Since you'll want to store these pointers in variables, and to avoid having dozens of them in the same scope (the main func for example or as global variables),
mow.cli's API was specifically tailored to take a func parameter (called CmdInitializer) which accepts the command struct.
This way, the command specific variables scope is limited to this function.
Interceptors
It is possible to define snippets of code to be executed before and after a command or any of its sub commands is executed.
For example, given an app with multiple commands but with a global flag which toggles a verbose mode:
app := cli.App("app", "bla bla")
verbose := app.Bool(cli.BoolOpt{
Name: "verbose",
Value: false,
Desc: "Enable debug logs",
})
app.Command("command1", "...", func(cmd *cli.Cmd) {
})
app.Command("command2", "...", func(cmd *cli.Cmd) {
})
Instead of repeating yourself by checking if the verbose flag is set or not, and setting the debug level in every command (and its sub-commands),
a before interceptor can be set on the `app` instead:
app.Before = func() {
if (*verbose) {
logrus.SetLevel(logrus.DebugLevel)
}
}
Whenever a valid command is called by the user, all the before interceptors defined on the app and the intermediate commands
will be called, in order from the root to the leaf.
Similarly, if you need to execute a code snippet after a command has been called, e.g. to cleanup resources allocated in before interceptors,
simply set the After field of the app struct or any other command.
After interceptors will be called, in order from the leaf up to the root (the opposite order of the Before interceptors).
Here's a diagram which shows in when and in which order multiple Before and After interceptors get executed:
+------------+ success +------------+ success +----------------+ success
| app.Before +---------------> cmd.Before +-------------> sub_cmd.Before +---------+
+------------+ +-+----------+ +--+-------------+ |
| | +-v-------+
error | error | | sub_cmd |
+-----------------------+ +-----------------------+ | Action |
| | +-+-------+
+------v-----+ +-----v------+ +----------------+ |
| app.After <---------------+ cmd.After <-------------+ sub_cmd.After <---------+
+------------+ always +------------+ always +----------------+ always
Spec
An app or command's call syntax can be customized using spec strings.
This can be useful to indicate that an argument is optional for example, or that 2 options are mutually exclusive.
You can set a spec string on:
* The app: to configure the syntax for global options and arguments
* A command: to configure the syntax for that command's options and arguments
In both cases, a spec string is assigned to the Spec field:
cp := cli.App("cp", "Copy files around")
cp.Spec = "[-R [-H | -L | -P]]"
And:
docker := cli.App("docker", "A self-sufficient runtime for linux containers")
docker.Command("run", "Run a command in a new container", func(cmd *cli.Cmd) {
cmd.Spec = "[-d|--rm] IMAGE [COMMAND [ARG...]]"
:
:
}
The spec syntax is mostly based on the conventions used in POSIX command line apps help messages and man pages:
Options
You can use both short and long option names in spec strings:
x.Spec="-f"
And:
x.Spec="--force"
In both cases, we required that the f or force flag be set
Any option you reference in a spec string MUST be explicitly declared, otherwise mow.cli will panic:
x.BoolOpt("f force", ...)
Arguments
Arguments are all-uppercased words:
x.Spec="SRC DST"
This spec string will force the user to pass exactly 2 arguments, SRC and DST
Any argument you reference in a spec string MUST be explicitly declared, otherwise mow.cli will panic:
x.StringArg("SRC", ...)
x.StringArg("DST", ...)
Ordering
Except for options, The order of the elements in a spec string is respected and enforced when parsing the command line arguments:
x.Spec = "-f -g SRC -h DST"
Consecutive options (-f and -g for example) get parsed regardless of the order they are specified in (both "-f=5 -g=6" and "-g=6 -f=5" are valid).
Order between options and arguments is significant (-f and -g must appear before the SRC argument).
Same goes for arguments, where SRC must appear before DST.
Optionality
You can mark items as optional in a spec string by enclosing them in square brackets :[...]
x.Spec = "[-x]"
Choice
You can use the | operator to indicate a choice between two or more items
x.Spec = "--rm | --daemon"
x.Spec = "-H | -L | -P"
x.Spec = "-t | DST"
Repetition
You can use the ... postfix operator to mark an element as repeatable:
x.Spec="SRC..."
x.Spec="-e..."
Grouping
You can group items using parenthesis. This is useful in combination with the choice and repetition operators (| and ...):
x.Spec = "(-e COMMAND)... | (-x|-y)"
The parenthesis in the example above serve to mark that it is the sequence of a -e flag followed by an argument that is repeatable, and that
all that is mutually exclusive to a choice between -x and -y options.
Option group
This is a shortcut to declare a choice between multiple options:
x.Spec = "-abcd"
Is equivalent to:
x.Spec = "(-a | -b | -c | -d)..."
I.e. any combination of the listed options in any order, with at least one option.
All options
Another shortcut:
x.Spec = "[OPTIONS]"
This is a special syntax (the square brackets are not for marking an optional item, and the uppercased word is not for an argument).
This is equivalent to a repeatable choice between all the available options.
For example, if an app or a command declares 4 options a, b, c and d, [OPTIONS] is equivalent to
x.Spec = "[-a | -b | -c | -d]..."
Inline option values
You can use the =<some-text> notation right after an option (long or short form) to give an inline description or value.
An example:
x.Spec = "[ -a=<absolute-path> | --timeout=<in seconds> ] ARG"
The inline values are ignored by the spec parser and are just there for the final user as a contextual hint.
Operators
The `--` operator can be used in a spec string to automatically treat everything following it as an options.
In other words, placing a `--` in the spec string automatically inserts a `--` in the same position in the program call arguments.
This lets you write programs like the `time` utility for example:
x.Spec = "time -lp [-- CMD [ARG...]]"
Spec Grammar
Here's the EBNF grammar for the Specs language:
spec -> sequence
sequence -> choice*
req_sequence -> choice+
choice -> atom ('|' atom)*
atom -> (shortOpt | longOpt | optSeq | allOpts | group | optional) rep?
shortOp -> '-' [A-Za-z]
longOpt -> '--' [A-Za-z][A-Za-z0-9]*
optSeq -> '-' [A-Za-z]+
allOpts -> '[OPTIONS]'
group -> '(' req_sequence ')'
optional -> '[' req_sequence ']'
rep -> '...'
And that's it for the spec language.
You can combine these few building blocks in any way you want (while respecting the grammar above) to construct sophisticated validation constraints
(don't go too wild though).
Behind the scenes, mow.cli parses the spec string and constructs a finite state machine to be used to parse the command line arguments.
mow.cli also handles backtracking, and so it can handle tricky cases, or what I like to call "the cp test"
cp SRC... DST
Without backtracking, this deceptively simple spec string cannot be parsed correctly.
For instance, docopt can't handle this case, whereas mow.cli does.
Default spec
By default, and unless a spec string is set by the user, mow.cli auto-generates one for the app and every command using this logic:
* Start with an empty spec string
* If at least one option was declared, append "[OPTIONS]" to the spec string
* For every declared argument, append it, in the order of declaration, to the spec string
For example, given this command declaration:
docker.Command("run", "Run a command in a new container", func(cmd *cli.Cmd) {
detached := cmd.BoolOpt("d detach", false, "Detached mode: run the container in the background and print the new container ID")
memory := cmd.StringOpt("m memory", "", "Memory limit (format: <number><optional unit>, where unit = b, k, m or g)")
image := cmd.StringArg("IMAGE", "", "")
args := cmd.StringsArg("ARG", "", "")
})
The auto-generated spec string would be:
[OPTIONS] IMAGE ARG
Which should suffice for simple cases. If not, the spec string has to be set explicitly.
Exiting
mow.cli provides the Exit function which accepts an exit code and exits the app with the provided code.
You are highly encouraged to call cli.Exit instead of os.Exit for the After interceptors to be executed.
*/
package cli