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 "special" 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*/