README.md
1go-flags: a go library for parsing command line arguments
2=========================================================
3
4[![GoDoc](https://godoc.org/github.com/jessevdk/go-flags?status.png)](https://godoc.org/github.com/jessevdk/go-flags) [![Build Status](https://travis-ci.org/jessevdk/go-flags.svg?branch=master)](https://travis-ci.org/jessevdk/go-flags) [![Coverage Status](https://img.shields.io/coveralls/jessevdk/go-flags.svg)](https://coveralls.io/r/jessevdk/go-flags?branch=master)
5
6This library provides similar functionality to the builtin flag library of
7go, but provides much more functionality and nicer formatting. From the
8documentation:
9
10Package flags provides an extensive command line option parser.
11The flags package is similar in functionality to the go builtin flag package
12but provides more options and uses reflection to provide a convenient and
13succinct way of specifying command line options.
14
15Supported features:
16* Options with short names (-v)
17* Options with long names (--verbose)
18* Options with and without arguments (bool v.s. other type)
19* Options with optional arguments and default values
20* Multiple option groups each containing a set of options
21* Generate and print well-formatted help message
22* Passing remaining command line arguments after -- (optional)
23* Ignoring unknown command line options (optional)
24* Supports -I/usr/include -I=/usr/include -I /usr/include option argument specification
25* Supports multiple short options -aux
26* Supports all primitive go types (string, int{8..64}, uint{8..64}, float)
27* Supports same option multiple times (can store in slice or last option counts)
28* Supports maps
29* Supports function callbacks
30* Supports namespaces for (nested) option groups
31
32The flags package uses structs, reflection and struct field tags
33to allow users to specify command line options. This results in very simple
34and concise specification of your application options. For example:
35
36```go
37type Options struct {
38 Verbose []bool `short:"v" long:"verbose" description:"Show verbose debug information"`
39}
40```
41
42This specifies one option with a short name -v and a long name --verbose.
43When either -v or --verbose is found on the command line, a 'true' value
44will be appended to the Verbose field. e.g. when specifying -vvv, the
45resulting value of Verbose will be {[true, true, true]}.
46
47Example:
48--------
49```go
50var opts struct {
51 // Slice of bool will append 'true' each time the option
52 // is encountered (can be set multiple times, like -vvv)
53 Verbose []bool `short:"v" long:"verbose" description:"Show verbose debug information"`
54
55 // Example of automatic marshalling to desired type (uint)
56 Offset uint `long:"offset" description:"Offset"`
57
58 // Example of a callback, called each time the option is found.
59 Call func(string) `short:"c" description:"Call phone number"`
60
61 // Example of a required flag
62 Name string `short:"n" long:"name" description:"A name" required:"true"`
63
64 // Example of a flag restricted to a pre-defined set of strings
65 Animal string `long:"animal" choice:"cat" choice:"dog"`
66
67 // Example of a value name
68 File string `short:"f" long:"file" description:"A file" value-name:"FILE"`
69
70 // Example of a pointer
71 Ptr *int `short:"p" description:"A pointer to an integer"`
72
73 // Example of a slice of strings
74 StringSlice []string `short:"s" description:"A slice of strings"`
75
76 // Example of a slice of pointers
77 PtrSlice []*string `long:"ptrslice" description:"A slice of pointers to string"`
78
79 // Example of a map
80 IntMap map[string]int `long:"intmap" description:"A map from string to int"`
81}
82
83// Callback which will invoke callto:<argument> to call a number.
84// Note that this works just on OS X (and probably only with
85// Skype) but it shows the idea.
86opts.Call = func(num string) {
87 cmd := exec.Command("open", "callto:"+num)
88 cmd.Start()
89 cmd.Process.Release()
90}
91
92// Make some fake arguments to parse.
93args := []string{
94 "-vv",
95 "--offset=5",
96 "-n", "Me",
97 "--animal", "dog", // anything other than "cat" or "dog" will raise an error
98 "-p", "3",
99 "-s", "hello",
100 "-s", "world",
101 "--ptrslice", "hello",
102 "--ptrslice", "world",
103 "--intmap", "a:1",
104 "--intmap", "b:5",
105 "arg1",
106 "arg2",
107 "arg3",
108}
109
110// Parse flags from `args'. Note that here we use flags.ParseArgs for
111// the sake of making a working example. Normally, you would simply use
112// flags.Parse(&opts) which uses os.Args
113args, err := flags.ParseArgs(&opts, args)
114
115if err != nil {
116 panic(err)
117}
118
119fmt.Printf("Verbosity: %v\n", opts.Verbose)
120fmt.Printf("Offset: %d\n", opts.Offset)
121fmt.Printf("Name: %s\n", opts.Name)
122fmt.Printf("Animal: %s\n", opts.Animal)
123fmt.Printf("Ptr: %d\n", *opts.Ptr)
124fmt.Printf("StringSlice: %v\n", opts.StringSlice)
125fmt.Printf("PtrSlice: [%v %v]\n", *opts.PtrSlice[0], *opts.PtrSlice[1])
126fmt.Printf("IntMap: [a:%v b:%v]\n", opts.IntMap["a"], opts.IntMap["b"])
127fmt.Printf("Remaining args: %s\n", strings.Join(args, " "))
128
129// Output: Verbosity: [true true]
130// Offset: 5
131// Name: Me
132// Ptr: 3
133// StringSlice: [hello world]
134// PtrSlice: [hello world]
135// IntMap: [a:1 b:5]
136// Remaining args: arg1 arg2 arg3
137```
138
139More information can be found in the godocs: <http://godoc.org/github.com/jessevdk/go-flags>
140