[Boost-users] Comments on the usability of program_options

From: Steve Byan (smb_at_[hidden])
Date: 2006-01-26 09:28:05

First let me mention that I greatly appreciate all the work done by  
the contributors to Boost. The library has been extremely helpful to  
me both as a class and template library and as a learning tool for  
template meta-programming.

In the spirit of constructive criticism, I'd like to offer a few  
usability observations arising from my first attempt to use  
program_options. I appreciate the flexibility, extensive feature set,  
and the extensibility of the library. I particularly like the  
unification of command-line options with configuration files; this is  
a very handy feature. However, I think the unification of program  
arguments with program options is less successful. I think the  
library would be better if arguments were a separate concept.

Unifying program arguments with program options has these consequences:

1) The error message produced by an excessive number of arguments is  
opaque to most users. The error message produced is "Error: unknown  
option foo", which I think would be better phrased as something along  
the lines of "Error: too many arguments". Since program_options  
doesn't distinguish options from arguments, it can't easily produce a  
better diagnostic message.

2) The usage description by default describes command-line arguments  
as options. E.g. the usage message is something like this:

Supported options:
   -h [ --help ]         produce this help message
   --device-file arg     scsi pass-thru device special file

To hide the "argument options" in the help message, program_options  
supports multiple options_descriptions, but puts the responsibility  
for hiding the "argument options" on the user of the library, and,  
unlike normal options, does not automatically provide a description  
of the argument in the help message. If arguments were instead  
treated as first-class concept instead of a mutant form of an option,  
the library could automatically handle these issues.

3) Somewhat related to issue #2, program_options doesn't generate a  
concise usage description help-message from the grammar. For example,  
it would be nice if options_desciption could provide a string like this:

Usage: scsi_tool [-h | --help] [-v | --verbose] <device-file>  
[<output-file>]

Additionally, it would be nice if program_options handled more of the  
validation and error reporting. Currently the user is responsible for  
checking for required arguments and generating an error if they are  
not supplied, and for coding the generation of a usage message when  
the options and arguments don't conform to the specified grammar.

An example of an alternative design which addresses these concerns  
(but which lacks many of the more sophisticated features of  
program_options) is Ole Laursen's commandoptions <http:// 
www.cs.aau.dk/~olau/commandoptions/>

Regards,
-Steve
--------
Steve Byan <smb_at_[hidden]>
Software Architect
Egenera, Inc.
165 Forest Street
Marlboro, MA 01752
[phone]