]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | */ |