7 ms·
The importance of user interface, illustrated by the Go flag package
- nkozyra 12y agoI hadn't noticed the flag package had changed. I'm not sure this brief post stressed the importance of UI, though.
- oaktowner 12y agoWell, I don't think the writer proved the importance of UI. But I think it serves as an excellent reminder that, for a cmdline program, the flags and arguments are the UI, they impact how people perceive your software and how productive they will be with it.
- lloydde 12y agoThis is good news. Being new to go, recently when I didn't get the expected behavior with a go cmd, not knowing any better I tried explicit =true.
- politician 12y agoHave you tried docopt? The usage string is a DSL which makes it painless to create command-line programs with great (and synchronized) help text. Check out an example: https://github.com/politician/azb.go/blob/master/src/cmd/azb/main.go#L187-L228 https://github.com/politician/azb.go/blob/master/src/cmd/azb...
- gnoway 12y agoI think you just illustrated the point of a prior blog post[0] linked from this one. [0] http://utcc.utoronto.ca/~cks/space/blog/programming/GoGetoptProblem http://utcc.utoronto.ca/~cks/space/blog/programming/GoGetopt...
- politician 12y agoWow, that post is spot-on; thanks.
- pico303 12y agoTry CLI from codegangsta. Quite a nice alternative to flag, with perks--not the least of which is beautifully formatted help text. https://github.com/codegangsta/cli https://github.com/codegangsta/cli
- wtf_is_up 12y agoI really like kingpin [1] as well. [1] https://github.com/alecthomas/kingpin https://github.com/alecthomas/kingpin
- sirclueless 12y agoThe go flag package has a nice API, but the user interface it creates is straight from its Rob Pike's Plan9 roots, and Linux users familiar with getopt command line interfaces will find it strange and perhaps even ugly. I wanted to create command line programs that look like traditional GNU/Unix utilities, so I wrote the https://github.com/ogier/pflag https://github.com/ogier/pflag package. It's a drop-in replacement for the flag package, just change the import line. It also adds some basic features, such as the common pattern of a flag with a long-hand form usable with a double --dash and a shorthand character with a single -d.
- rsc 12y agoThe Go flag package has nothing to do with Plan 9. Like Unix, Plan 9 had single-dash single-letter options ONLY. The long option syntax of getopt is a BSD/GNU-ism, not from Unix. The Go flag package's command lines adopt the observation made by the Google C++ command line flag parser (https://code.google.com/p/gflags https://code.google.com/p/gflags): the long/short --/- two-names-for-every-flag dichotomy was useful for backwards compatibility when recreating original Unix commands, but for new programs, it doesn't pull its weight. At the cost of requiring that each option be specified with a separate command-line argument, you can drop the distinction between - and -- entirely. (This is similar to what X11 programs do, although I believe they do not admit --x as a synonym for -x.) It's not clear to me what is "ugly" about not having to keep alternating between - and -- as you spell out options on the command line.
- burke 12y ago> It's not clear to me what is "ugly" about not having to keep alternating between - and -- as you spell out options on the command line. It's about the principle of least surprise. Regardless of whether double-dash opts came from UNIX or GNU (and obviously you are correct in that they came from BSD/GNU), they're the convention nowadays and it's less confusing for end users to just embrace the convention. Go has bucked the (recent) tradition on a lot of different fronts, which I love it for, but the flag package -- the interface to the users of the software, not the authors -- is one place I don't really think it's quite as appropriate. Certainly, Google is able to make these sort of changes in its internal world, and reach a high enough percentage of software that the new choice becomes normal, but Go will probably never have enough mindshare in the extraGoogle for its CLI parsing to not be "a little weird". --- As an addendum, I happily use the builtin flag package for software that is consumed primarily by my team. For software I expect other teams to use, who don't necessarily care about the fact that it was written in Go, I prefer pflag.
- amouat 12y agoI agree with this. Docker use the same flag style and it was confusing enough that it was wrongly documented for a long time: https://github.com/docker/docker/issues/10517 https://github.com/docker/docker/issues/10517
- martinp 12y agoI always use go-flags [1] in my Go programs. It has support for GNU-style options, pretty help output, subcommands, automatic parsing of more complex arguments (e.g. time.Duration) among other things. I do wish they would improve the included flags package though. There are lots of nice third party packages, but having a proper one in the standard library would've been better. [1] https://github.com/jessevdk/go-flags https://github.com/jessevdk/go-flags
- dvirsky 12y agoCame here to say this. go-flags is an excellent package, and makes great use of struct-tags. An extra bonus is that it can parse .ini files and command-line flags into the same underlying config struct, allowing one to override the other.
- tptacek 12y agoI like Go's flag library. Also: getopt is pretty easy to write (if you're going for strict Unix style, you're presumably not looking for a featureful getopt), and that interface style is abused far more often than it's deployed gracefully. Some of the worst Unix command line interfaces† are the product of getopt, or the belief that there's an idiomatic Unix argument handling convention and that the idiom is getopt. If your argument parsing needs are complicated, you should break out an actual parser. Finally: I see the benefit of having an auto-generated usage message that is better than a bad auto-generated usage message, but if you really want artisanal command line tools, shouldn't you be writing artisanal usage messages? C programmers as a rule didn't count on the library to generate the usage message for them. † See for instance nmap
- lukeschlather 12y agoI think the ideal argument parser allows you basically to write a spec for your program, and then automatically generates a parser that will both turn options specified by the user into a map, as well as print the relevant parts of the spec when invalid input is given. Could you elaborate on why you believe flag is preferable to something like what I've described? (I'm coming from Ruby-land where Trollop basically does that.) I'm struggling to understand what's preferable about needing to roll your own parser and write documentation when you could just describe your program and have the parser/documentation auto-generated.
- tptacek 12y agoTrollop seems like a "better getopt". Conceptually it's still a series of flags. For simple programs, flags might be all you need, and there's value in cohering with all other Unix tools that communicate strictly through flags. But when your needs get more complicated, when the information being communicated on the command line starts getting more dense, the concept "flags" becomes an obstacle. Far too many programs keep leaning on flags far past the point where the abstraction breaks down. You start to feel like you're writing small programs in the confining language of command line flags. A great example I think is "tcpdump", because it exhibits both behaviors: it has a hideously overcomplicated getopt configurator and a relatively graceful parsed language for describing capture filters (those filters being the most important option given to tcpdump). You can see how tcpdump would be better off if most of the flags were hoisted into that filter language. (They can't easily be, of course, because that filter language is actually parsed --- and then compiled --- by libpcap, not tcpdump).
- zobzu 12y agoI cant agree more with the importance of consistency UI in CLI programs. It's unfortunate that newer programs overlook it. I'm glad for the recent changes from the flag package which has also been annoying me previously ;) When i type blah -h or --help i expect help to pop up. I expect it to tell me about USAGE with [optional] and <required>. I expect the same spacing and readability as the vast majority (which is basically dictated by GNU getops. Else, its a pain. Heck, even git doesn't follow this and as a result is a little more painful that needs to be. Imagine a GUI program with every window having a different close, resize, etc button/menu. Hell.
- tomcam 12y agoCouldn't a perfectly adequate parser have been written in about the same time as the blog post?
- lazyjones 12y agoI like the present (older) output because it's absolutely unambiguous. If I have to read a textual description to understand whether it's a default argument, whether it takes an optional parameter, or how precisely it is used, it's less clear especially when the text is badly written. The current output is probably also perfectly suitable for parsing (by a program).
- mwsherman 12y agoThe flags package is one of the few Go stdlib’s where I haven’t been won over; I felt that the cost of my understanding the abstraction was higher than just implementing the logic. https://github.com/clipperhouse/gen/blob/master/main.go#L67 https://github.com/clipperhouse/gen/blob/master/main.go#L67
- Animats 12y agoCould be worse. There's a build tool for Mozilla add-ons where the flags go after the file argument.