95 lines
4.0 KiB
Plaintext
95 lines
4.0 KiB
Plaintext
/** @page rationale Rationale
|
|
|
|
@section code_size Focus on code size
|
|
|
|
The program options library has two important properties:
|
|
- runtime performance is not important. After all, command line processing
|
|
is done only once, and the amount of data is small.
|
|
- code size matters. Since parsing command line is utility task, users
|
|
won't be glad to have lots of code linked to every binary which has
|
|
options.
|
|
|
|
For the above reasons, the the library is designed so that it can be easily
|
|
used as shared library, with minimum code on the side of main application.
|
|
In particular, templates are used only where necessary, for example for
|
|
validation of user-defined types. In other places, boost::function is
|
|
used to allow customization, but keep templates out of the public
|
|
interface.
|
|
|
|
@section string_vs_enums Strings vs. enums
|
|
|
|
In some places, the library uses strings to convey information that
|
|
could be represented by enumerations or values. For example,
|
|
the program_options::option_description class allows to add "?" to the
|
|
parameter name to specify that the parameter is optional. For another
|
|
example, while program_options::cmdline class allows to obtain the
|
|
index of option, it does not require to specify an index for each option,
|
|
and it's possible to tell options by their names.
|
|
|
|
Such interface appears to be much more usable. If we were using
|
|
enumeration for different properties of parameter, there would be
|
|
another argument to many functions, the need to type long, possible
|
|
qualified names, and little advantage.
|
|
|
|
That little advantage is that if you type a wrong enumeration name,
|
|
you'd get a compile error. If you type '!' instead of '?' after parameter
|
|
name, you'd get incorrect behaviour. However, such errors are deemed
|
|
rare.
|
|
|
|
@section char_vs_string const char* vs. std::string
|
|
|
|
Most of the interface uses const char* where std::string seems a natural
|
|
choice. The reason is that those functions are called many times: for
|
|
example to declare all options. They are typically called with string
|
|
literals, and implicit conversion to string appears to take a lot of
|
|
code space. Providing both std::string and const char* version would
|
|
considerably bloat the interface. Since passing std::string is considered
|
|
rare, only const char* versions are provided.
|
|
|
|
@section init_syntax Initialization syntax
|
|
|
|
The syntax used for creating options_description instance was designed to
|
|
be as easy as possible in the most common case. Consider:
|
|
@code
|
|
desc.add_options()
|
|
("verbose", "", "verbosity level")
|
|
("magic", "int", "magic value").notify(some_func)
|
|
;
|
|
@endcode
|
|
Here, most common properties of options: name, presense of parameter and
|
|
description, are specified very concisely, and additional properties can
|
|
be given quite naturally, too.
|
|
|
|
Another possibility would be:
|
|
@code
|
|
option_description d1(...), d2(...);
|
|
desc.add(d1 & d2);
|
|
@endcode
|
|
or
|
|
@code
|
|
option_description d1(...), d2(...);
|
|
desc = d1, d2;
|
|
@endcode
|
|
|
|
The drawback is the need to explicitly create new objects and give names
|
|
to them. The latter problem can be helped if objects are created inside
|
|
expressions:
|
|
@code
|
|
desc = option_description(...), option_description(...)
|
|
@endcode
|
|
but there's still extra typing.
|
|
|
|
@section help_handling Handling of --help
|
|
|
|
It was suggested by Gennadiy Rozental that occurrence of <tt>--help</tt>
|
|
on command line results in throwing an exception. Actually, the
|
|
"special" option must have been configurable. This was not
|
|
implemented, because applications might reasonable want to process
|
|
the rest of command line even of <tt>--help</tt> was seen. For example,
|
|
<tt>--verbose</tt> option can control how much help should be output,
|
|
or there may be several subcommand with different help screens.
|
|
|
|
|
|
|
|
|
|
*/ |