# Changes since formal review

During formal review, a large number of changes was suggested. To make using the new version easier, the implemented changes are described below.

Let's start with an example. The following is a typical code for the reviewed version:

          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);

The code for the current version would look like:

          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);

Let's examine all the changes in detail

## Option description

- The `parameter` function was renamed to `value`. Rationale: "paramater" is yet another term with no clear definition, while "value" is already used everywhere in docs.

- The default value is specified in different place, and should use the value of desired type, not string. Previous code was:

                  ("magic", parameter<int>("value")).default_value("43")

  and the new code is

                  ("magic", parameter<int>("value")->default_value(43));

  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.

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

      ("numbers", parameter<int>("n+"))

  has became

      ("numbers", value<int>()->multitoken())

  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.

## Parsers

- The `options_and_argument` class was removed.

- The `cmdline` and `config_file` classes were removed from the public interface. Various command line styles are now declared in the `command_line_style` subnamespace.

- New function `parse_environment` was added.

- Support for positional options was added

## Storage

- The `notify` function should be called after all sources are stored in a `variales_map` instance. This is done to property support priority of configuration sources.