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
|
# getopt
Package getopt provides traditional getopt processing for implementing
commands that use traditional command lines. The standard Go flag package
cannot be used to write a program that parses flags the way ls or ssh does,
for example. There are two versions, v1 and v2, both named getopt, that
use the following import paths:
```
"github.com/pborman/getopt" // version 1
"github.com/pborman/getopt/v2" // version 2
```
This README describes version 2 of the package, which has a simplified API.
## Usage
Getopt supports functionality found in both the standard BSD getopt as well
as (one of the many versions of) the GNU getopt_long. Being a Go package,
this package makes common usage easy, but still enables more controlled usage
if needed.
Typical usage:
```
Declare flags and have getopt return pointers to the values.
helpFlag := getopt.Bool('?', "display help")
cmdFlag := getopt.StringLong("command", 'c', "default", "the command)
Declare flags against existing variables.
var {
fileName = "/the/default/path"
timeout = time.Second * 5
verbose bool
}
func init() {
getopt.Flag(&verbose, 'v', "be verbose")
getopt.FlagLong(&fileName, "path", 0, "the path")
getopt.FlagLong(&timeout, "timeout", 't', "some timeout")
}
func main() {
Parse the program arguments
getopt.Parse()
Get the remaining positional parameters
args := getopt.Args()
...
```
If you don't want the program to exit on error, use getopt.Getopt:
```
err := getopt.Getopt(nil)
if err != nil {
code to handle error
fmt.Fprintln(os.Stderr, err)
}
```
## Flag Syntax
Support is provided for both short (-f) and long (--flag) options. A single
option may have both a short and a long name. Each option may be a flag or a
value. A value takes an argument.
Declaring no long names causes this package to process arguments like the
traditional BSD getopt.
Short flags may be combined into a single parameter. For example, "-a -b -c"
may also be expressed "-abc". Long flags must stand on their own "--alpha
--beta"
Values require an argument. For short options the argument may either be
immediately following the short name or as the next argument. Only one short
value may be combined with short flags in a single argument; the short value
must be after all short flags. For example, if f is a flag and v is a value,
then:
```
-vvalue (sets v to "value")
-v value (sets v to "value")
-fvvalue (sets f, and sets v to "value")
-fv value (sets f, and sets v to "value")
-vf value (set v to "f" and value is the first parameter)
```
For the long value option val:
```
--val value (sets val to "value")
--val=value (sets val to "value")
--valvalue (invalid option "valvalue")
```
Values with an optional value only set the value if the value is part of the
same argument. In any event, the option count is increased and the option is
marked as seen.
```
-v -f (sets v and f as being seen)
-vvalue -f (sets v to "value" and sets f)
--val -f (sets v and f as being seen)
--val=value -f (sets v to "value" and sets f)
```
There is no convience function defined for making the value optional. The
SetOptional method must be called on the actual Option.
```
v := String("val", 'v', "", "the optional v")
Lookup("v").SetOptional()
var s string
FlagLong(&s, "val", 'v', "the optional v).SetOptional()
```
Parsing continues until the first non-option or "--" is encountered.
The short name "-" can be used, but it either is specified as "-" or as part
of a group of options, for example "-f-". If there are no long options
specified then "--f" could also be used. If "-" is not declared as an option
then the single "-" will also terminate the option processing but unlike
"--", the "-" will be part of the remaining arguments.
## Advanced Usage
Normally the parsing is performed by calling the Parse function. If it is
important to see the order of the options then the Getopt function should be
used. The standard Parse function does the equivalent of:
```
func Parse() {
if err := getopt.Getopt(os.Args, nil); err != nil {
fmt.Fprintln(os.Stderr, err)
s.usage()
os.Exit(1)
}
}
```
When calling Getopt it is the responsibility of the caller to print any
errors.
Normally the default option set, CommandLine, is used. Other option sets may
be created with New.
After parsing, the sets Args will contain the non-option arguments. If an
error is encountered then Args will begin with argument that caused the
error.
It is valid to call a set's Parse a second time to amend the current set of
flags or values. As an example:
```
var a = getopt.Bool('a', "", "The a flag")
var b = getopt.Bool('b', "", "The a flag")
var cmd = ""
var opts = getopt.CommandLine
opts.Parse(os.Args)
if opts.NArgs() > 0 {
cmd = opts.Arg(0)
opts.Parse(opts.Args())
}
```
If called with set to { "prog", "-a", "cmd", "-b", "arg" } then both and and
b would be set, cmd would be set to "cmd", and opts.Args() would return {
"arg" }.
Unless an option type explicitly prohibits it, an option may appear more than
once in the arguments. The last value provided to the option is the value.
## Builtin Types
The Flag and FlagLong functions support most standard Go types. For the
list, see the description of FlagLong below for a list of supported types.
There are also helper routines to allow single line flag declarations. These
types are: Bool, Counter, Duration, Enum, Int16, Int32, Int64, Int, List,
Signed, String, Uint16, Uint32, Uint64, Uint, and Unsigned.
Each comes in a short and long flavor, e.g., Bool and BoolLong and include
functions to set the flags on the standard command line or for a specific Set
of flags.
Except for the Counter, Enum, Signed and Unsigned types, all of these types
can be declared using Flag and FlagLong by passing in a pointer to the
appropriate type.
## Declaring New Flag Types
A pointer to any type that implements the Value interface may be passed to
Flag or FlagLong.
## VALUEHELP
All non-flag options are created with a "valuehelp" as the last parameter.
Valuehelp should be 0, 1, or 2 strings. The first string, if provided, is
the usage message for the option. If the second string, if provided, is the
name to use for the value when displaying the usage. If not provided the
term "value" is assumed.
The usage message for the option created with
```
StringLong("option", 'o', "defval", "a string of letters")
```
is
```
-o, -option=value
```
while the usage message for the option created with
```
StringLong("option", 'o', "defval", "a string of letters", "string")
```
is
```
-o, -option=string
```
|
