123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150 |
- <?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:
- -->
|