ceph/src/boost/libs/program_options/doc/rationale.dox

   1 /** @page rationale Rationale
   2
   3     @section code_size Focus on code size
   4
   5     The program options library has two important properties:
   6     - runtime performance is not important. After all, command line processing
   7       is done only once, and the amount of data is small.
   8     - code size matters. Since parsing command line is utility task, users
   9     won't be glad to have lots of code linked to every binary which has
  10     options.
  11
  12     For the above reasons, the the library is designed so that it can be easily
  13     used as shared library, with minimum code on the side of main application.
  14     In particular, templates are used only where necessary, for example for
  15     validation of user-defined types. In other places, boost::function is
  16     used to allow customization, but keep templates out of the public
  17     interface.
  18
  19     @section string_vs_enums Strings vs. enums
  20
  21     In some places, the library uses strings to convey information that
  22     could be represented by enumerations or values. For example,
  23     the program_options::option_description class allows to add "?" to the
  24     parameter name to specify that the parameter is optional. For another
  25     example, while program_options::cmdline class allows to obtain the
  26     index of option, it does not require to specify an index for each option,
  27     and it's possible to tell options by their names.
  28
  29     Such interface appears to be much more usable. If we were using
  30     enumeration for different properties of parameter, there would be
  31     another argument to many functions, the need to type long, possible
  32     qualified names, and little advantage.
  33
  34     That little advantage is that if you type a wrong enumeration name,
  35     you'd get a compile error. If you type '!' instead of '?' after parameter
  36     name, you'd get incorrect behaviour.  However, such errors are deemed
  37     rare.
  38
  39     @section char_vs_string const char* vs. std::string
  40
  41     Most of the interface uses const char* where std::string seems a natural
  42     choice. The reason is that those functions are called many times: for
  43     example to declare all options. They are typically called with string
  44     literals, and implicit conversion to string appears to take a lot of
  45     code space. Providing both std::string and const char* version would
  46     considerably bloat the interface. Since passing std::string is considered
  47     rare, only const char* versions are provided.
  48
  49     @section init_syntax Initialization syntax
  50
  51     The syntax used for creating options_description instance was designed to
  52     be as easy as possible in the most common case. Consider:
  53     @code
  54     desc.add_options()
  55             ("verbose", "", "verbosity level")
  56             ("magic", "int", "magic value").notify(some_func)
  57             ;
  58     @endcode
  59     Here, most common properties of options: name, presense of parameter and
  60     description, are specified very concisely, and additional properties can
  61     be given quite naturally, too.
  62
  63     Another possibility would be:
  64     @code
  65         option_description d1(...), d2(...);
  66         desc.add(d1 & d2);
  67     @endcode
  68     or
  69     @code
  70         option_description d1(...), d2(...);
  71         desc = d1, d2;
  72     @endcode
  73
  74     The drawback is the need to explicitly create new objects and give names
  75     to them. The latter problem can be helped if objects are created inside
  76     expressions:
  77     @code
  78         desc = option_description(...), option_description(...)
  79     @endcode
  80     but there's still extra typing.
  81
  82     @section help_handling Handling of --help
  83
  84     It was suggested by Gennadiy Rozental that occurrence of <tt>--help</tt>
  85     on command line results in throwing an exception. Actually, the
  86     &quot;special&quot; option must have been configurable. This was not
  87     implemented, because applications might reasonable want to process
  88     the rest of command line even of <tt>--help</tt> was seen. For example,
  89     <tt>--verbose</tt> option can control how much help should be output,
  90     or there may be several subcommand with different help screens.
  91
  92
  93
  94
  95 */