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