1 2 Program options post-review development plan. 3 40. Convert all documentation to BoostBook format 5 61. (done) 7 Simplify and clarify interface. 8 9 It turns out that most users are interested in 'variables_map' class, so 10 it must be possible to use it directly, without even knowing about 11 'options_and_arguments'. The proposed interface is: 12 13 options_description desc; 14 .... 15 variables_map vm; 16 load_from_command_line(vm, desc, argc, argv); 17 182. (done) 19 Better separation of syntaxic and semantic processing, as suggested by 20 Pavol Droba. 21 22 The problem with current 'option_description' interface is that the 23 'validator' and 'notifier' callbacks are not really usable by ordinary 24 users --- it's extender's interface. The current 'parameter' function uses 25 those callback to provide user-friendly semantic interface, but it's not 26 documented nor completely worked out. 27 28 In the new interface, the second parameter of 'option_description' ctor 29 will have two possibilities: just a string and a pointer to a new class 30 'value_descriptor'. When passed the latter, it will invoke the instance on 31 itself, and then delete the object. A function 'value' will be provided, 32 that will create value specific for a type. 33 34 Example 35 ("magic", value<int>("n", &n)->default_value(10), "magic value"). 36 37 The 'value' function will create instances of 'typed_value_descriptor' 38 type, with the following methods: 39 - default_value 40 - interpreter 41 - validator 42 - notifier 43 44 The 'option_description' class we'll have two attributes to support 45 semantic operation: 'generator', which will handle conversion from string 46 into value (including application of default value), and 'notifier'. Similiar 47 to the the current design, those attributes will be set by 48 'value_descriptor' instances. 49 50 Another function, "bool_switch" will create value descriptor for type bool, 51 with default value of false. The function is needed to avoid special-casing 52 'value' function on bool type, which was considered confusing (Neal D. Becker). 53 543. (done) Support for positional options. 55 56 Positional options will be treated uniformly with ordinary ones. User will 57 be able to specify that, for example, third positional option is to be 58 interpreted as option "output-file" with the same value. 59 60 The user interface will be simple: user will provide two instanes of 61 'options_description' to functions which parse command line. For example. 62 63 options_description desc; 64 desc.add_options() 65 ("magic", "n", "magic value") 66 ; 67 68 options_description pdesc; 69 pdesc.add_options() 70 ("output-file", "n", "output file") 71 ("input-files*", value< vector<string> >("n"), "files") 72 ; 73 74 variables_map vm; 75 load_from_command_line(vm, desc, pdesc, argc, argv); 76 774. (done, except for registry) 78 Multiple sources improvement. 79 80 Need to implement support for registry/environment. 81 Also, must devise a way to handle different naming of option in 82 sources. Lastly, the storing of values into program variables should 83 become part of 'variables_map' interface. 84 855. Improve documentation. 86 87 Chuck Messenger: 88 "When code is given for an example program, after the code, give examples of 89 using the program, along with the expected output." 90 91 Pavol Droba: 92 "I would prefer a few chapters explaining various components of the 93 library, each followed by a reference." 94 95 Pavel Vozenilek: 96 > Documentation should contain list of compilers the library works on and 97 > also info whether MSVC 6 port is feasible or not. 98 > 99 > The non-Doxygen part of documentation can be also a bit expanded: e.g. I 100 > would welcome some high level overview of the algorithms and structures and 101 > info about expected CPU/memory consumption. 102 > 103 > Also info whether there are any internal limits (like option length) . 104 > 105 > Some examples may be bit more annotated, also contain what is expected 106 > output. 107 108 Syntax highligting. 109 110 Document "*" in option names 111 Automated tests for examples? 112 (new) Comments inside code snippets? 113 (new) Table of all symbols 114 115 1166. (deferred) 117 Unicode support 118 119 - unicode in argv/argc 120 - Unicode in config files not supported 121 ( 122 The difference between ASCII and unicode files is: 123 - big endian UTF16 starts with 2 bytes FE FF 9mandatory by Unicode 124 standard) - little endian UTF16 starts with FF FE 125 - UTF8 text starts with EF BB BF 126 127 Pavel Vozenilek 128 ) 129 1307. Config file improvements 131 132 - should have "allow_unregistered" for config_file. 133 - (done) bool options in config file do not work. 134 - "#" inside strings, in config files (Pavel Vozenilek) 135 1368. 137 Cmdline improvements 138 139 - must be able to parse WinMain string 140 - support for response files 141 1429. Other changes. 143 144 - (outdated) get_value -> value (Beman) 145 - (done) is "argv" const in std, or not? Adjust docs if not. 146 - variables_map::count_if, find_if (Tanton Gibbs) 147 - Works with exceptions disabled. 148 - (outdated) disallow empty name for the 'parameter' function 149 - check for prefixes if 'allow_guessing' is on 150 - check for duplicate declaration of options. 151 - test additional parser 152 - Show default values in help output 153 - Adaptive field width 154 - Mandatory options (2 votes (second Jonathan Graehl)) 155 - (new) return vector from parsers by auto_ptr, not by value? 156 - (new) rename value_semantic into value_description 157 - (new) output for positional_options_description 158 - (new) variables_map should throw when value not found 159 - (important) decide where we check that the number of passed option 160 tokens is less than the allowed number. In parser or later? 161 - (important) what if the same option has different definitions? 162 - (new) We lost the ability to specify options_description instance 163 in call to 'store'. So now we can't store just subset of options. 164 Is it a problem? 165 - (new) Improve formatting of 'arg'. 166 - (new) revive real and regexp examples. 167 - (new) even more simpler syntax for assignent to var? 168 169 17010. Uncertain 171 - Function to get program name 172 - Order of 'description' and 'value'. 173 174 17511. (new) Look at all "TODO" comments. 176 (new) Check that all methods are documented. 177 178 17912. Deferred 180 181 - setting a flag when option is found 182