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