]>
Commit | Line | Data |
---|---|---|
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 | --> |