1
- # Options taking varying numbers of option-arguments
1
+ <!-- omit from toc -->
2
+ # Options in Depth
2
3
3
4
The README covers declaring and using options, and mostly parsing will work the way you and your users expect. This page covers some special cases
4
5
and subtle issues in depth.
@@ -8,8 +9,10 @@ and subtle issues in depth.
8
9
- [ Alternative: Make ` -- ` part of your syntax] ( #alternative-make-----part-of-your-syntax )
9
10
- [ Alternative: Put options last] ( #alternative-put-options-last )
10
11
- [ Alternative: Use options instead of command-arguments] ( #alternative-use-options-instead-of-command-arguments )
11
- - [ Combining short options, and options taking arguments] ( #combining-short-options-and-options-taking-arguments )
12
- - [ Combining short options as if boolean] ( #combining-short-options-as-if-boolean )
12
+ - [ Combining short options, and options taking arguments] ( #combining-short-options-and-options-taking-arguments )
13
+ - [ Combining short options as if boolean] ( #combining-short-options-as-if-boolean )
14
+
15
+ ## Options taking varying numbers of option-arguments
13
16
14
17
Certain options take a varying number of arguments:
15
18
@@ -20,11 +23,11 @@ program
20
23
.option (' --test [name...]' ) // 0 or more
21
24
```
22
25
23
- This page uses examples with options taking 0 or 1 arguments, but the discussions also apply to variadic options taking more arguments.
26
+ This section uses examples with options taking 0 or 1 arguments, but the discussions also apply to variadic options taking more arguments.
24
27
25
28
For information about terms used in this document see: [ terminology] ( ./terminology.md )
26
29
27
- ## Parsing ambiguity
30
+ ### Parsing ambiguity
28
31
29
32
There is a potential downside to be aware of. If a command has both
30
33
command-arguments and options with varying option-arguments, this introduces a parsing ambiguity which may affect the user of your program.
@@ -73,7 +76,7 @@ ingredient: cheese
73
76
74
77
If you want to avoid your users needing to learn when to use ` -- ` , there are a few approaches you could take.
75
78
76
- ### Alternative: Make ` -- ` part of your syntax
79
+ #### Alternative: Make ` -- ` part of your syntax
77
80
78
81
Rather than trying to teach your users what ` -- ` does, you could just make it part of your syntax.
79
82
@@ -98,7 +101,7 @@ technique: scrambled
98
101
ingredient: cheese
99
102
```
100
103
101
- ### Alternative: Put options last
104
+ #### Alternative: Put options last
102
105
103
106
Commander follows the GNU convention for parsing and allows options before or after the command-arguments, or intermingled.
104
107
So by putting the options last, the command-arguments do not get confused with the option-arguments.
@@ -120,7 +123,7 @@ technique: scrambled
120
123
ingredient: cheese
121
124
```
122
125
123
- ### Alternative: Use options instead of command-arguments
126
+ #### Alternative: Use options instead of command-arguments
124
127
125
128
This is a bit more radical, but completely avoids the parsing ambiguity!
126
129
@@ -178,7 +181,7 @@ halal servings: v
178
181
179
182
If you wish to use options taking varying arguments as boolean options, you need to specify them separately.
180
183
181
- ```
184
+ ``` console
182
185
$ collect -a -v -l
183
186
any servings: true
184
187
vegan servings: true
@@ -190,7 +193,7 @@ halal servings: true
190
193
Before Commander v5, combining a short option and the value was not supported, and combined short flags were always expanded.
191
194
So ` -avl ` expanded to ` -a -v -l ` .
192
195
193
- If you want backwards compatible behaviour, or prefer combining short options as booleans to combining short option and value,
196
+ If you want backwards compatible behaviour, or prefer combining short options as booleans to combining short option and value,
194
197
you may change the behavior.
195
198
196
199
To modify the parsing of options taking an optional value:
0 commit comments