1<?xml version="1.0" standalone="yes"?> 2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 3 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd" 4[ 5 <!ENTITY % entities SYSTEM "program_options.ent" > 6 %entities; 7]> 8<section id="program_options.changes"> 9 <title>Changes since formal review</title> 10 11 <para>During formal review, a large number of changes was suggested. To make 12 using the new version easier, the implemented changes are described 13 below.</para> 14 15 <para>Let's start with an example. The following is a typical code for the 16 reviewed version:<programlisting> 17 options_description desc; 18 desc.add_options() 19 ("magic", parameter<int>("value"), "magic value for the program") 20 .default_value("43") 21 22 variables_map vm; 23 options_and_arguments oa1 = parse_command_line(ac, av, desc); 24 store(oa1, vm, desc) 25 26 variables_map vm2; 27 ifstream ifs("main.cfg"); 28 options_and_arguments oa2 = parse_config_file(ifs, desc); 29 store(oa1, vm2, desc); 30 31 vm.next(&vm2); 32 </programlisting>The code for the current version would look like: 33 <programlisting> 34 options_description desc; 35 desc.add_options() 36 ("magic", value<int>()->default_value(43), 37 "magic value for the program") 38 39 variables_map vm; 40 41 store(parse_command_line(ac, av, desc), vm); 42 43 ifstream ifs("main.cfg"); 44 store(parse_command_line(ifs, desc), vm); 45 46 notify(vm); 47 </programlisting> 48 </para> 49 50 <para>Let's examine all the changes in detail</para> 51 52 <section> 53 <title>Option description</title> 54 55 <itemizedlist> 56 <listitem> 57 <para>The <code>parameter</code> function was renamed to 58 <code>value</code>. Rationale: "paramater" is yet another term with no 59 clear definition, while "value" is already used everywhere in 60 docs.</para> 61 </listitem> 62 <listitem> 63 <para>The default value is specified in different place, and should 64 use the value of desired type, not string. Previous code was: 65 <programlisting> 66 ("magic", parameter<int>("value")).default_value("43") 67 </programlisting> 68 and the new code is 69 <programlisting> 70 ("magic", parameter<int>("value")->default_value(43)); 71 </programlisting> 72 Rationale: the new way is less restrictive. At the same time, the 73 new design allows to implement other behaviour, like validation of 74 the value, which require knowledge of the value type. 75 </para> 76 </listitem> 77 78 <listitem> 79 <para>The number of token value can take on command line, which was 80 specified using character suffix appended to value name, is now 81 specified using more explicit member calls. Moreover, it's not longer 82 possible to specify the "value name". 83 For example: 84<programlisting>("numbers", parameter<int>("n+"))</programlisting> 85 has became 86<programlisting>("numbers", value<int>()->multitoken())</programlisting> 87 Rationale: such modifiers tend to make command line usage less 88 clear. There's no need to make evil things too easy to do. 89 The "value name" had only two roles: specifying modifiers, and 90 telling what to output in automated help. The first role has became 91 obsolete, and the second was questionable too. It was very unclear how 92 to decide on the best "value name", and eventually the selection was randon. 93 </para> 94 </listitem> 95 </itemizedlist> 96 97 </section> 98 99 <section> 100 <title>Parsers</title> 101 102 103 <itemizedlist> 104 <listitem> 105 <para>The <code>options_and_argument</code> class was removed.</para> 106 </listitem> 107 <listitem> 108 <para>The <code>cmdline</code> and <code>config_file</code> classes 109 were removed from the public interface. Various command line styles 110 are now declared in the <code>command_line_style</code> subnamespace. 111 </para> 112 </listitem> 113 114 <listitem> 115 <para>New function <code>parse_environment</code> was added.</para> 116 </listitem> 117 118 <listitem> 119 <para>Support for positional options was added</para> 120 </listitem> 121 122 </itemizedlist> 123 </section> 124 125 126 <section> 127 <title>Storage</title> 128 129 <itemizedlist> 130 <listitem> 131 <para>The <code>notify</code> function should be called after all 132 sources are stored in a <code>variales_map</code> instance. This is 133 done to property support priority of configuration sources. 134 </para> 135 </listitem> 136 </itemizedlist> 137 </section> 138 139 140 141</section> 142 143<!-- 144 Local Variables: 145 mode: xml 146 sgml-indent-data: t 147 sgml-parent-document: ("program_options.xml" "section") 148 sgml-set-face: t 149 End: 150-->