Making mutable sets explicit (#200)

Author: henryiii

CHANGELOG.md

@@ -1,14 +1,15 @@
 ## Version 1.7: Parse breakup (in progress)
 
 The parsing procedure now maps much more sensibly to complex, nested subcommand structures. Each phase of the parsing happens on all subcommands before moving on with the next phase of the parse. This allows several features, like required environment variables, to work properly even through subcommand boundaries.
-Passing the same subcommand multiple times is better supported. Several new features were added as well, including Windows style option support, parsing strings directly, and ignoring underscores in names.
+Passing the same subcommand multiple times is better supported. Several new features were added as well, including Windows style option support, parsing strings directly, and ignoring underscores in names. Adding a set that you plan to change later must now be done with `add_mutable_set`.
 
 * Support Windows style options with `->allow_windows_style_options`. [#187] On by default on Windows. [#190]
 * Added `parse(string)` to split up and parse a command-line style string directly. [#186]
 * Added `ignore_underscore` and related functions, to ignore underscores when matching names. [#185]
 * The default INI Config will now add quotes to strings with spaces [#195]
 * The default message now will mention the help-all flag also if present [#197]
 * Added `->description` to set Option descriptions [#199]
+* Mutating sets (introduced in Version 1.6) now have a clear add method, `add_mutable_set*`, since the set reference should not expire [#200]
 * Subcommands now track how many times they were parsed in a parsing process. `count()` with no arguments will return the number of times a subcommand was encountered. [#179]
 * Parsing is now done in phases: `shortcurcuits`, `ini`, `env`, `callbacks`, and `requirements`; all subcommands complete a phase before moving on. [#179]
 * Calling parse multiple times is now officially supported without `clear` (automatic). [#179]
@@ -28,6 +29,7 @@ Passing the same subcommand multiple times is better supported. Several new feat
 [#197]: https://github.com/CLIUtils/CLI11/pull/197
 [#195]: https://github.com/CLIUtils/CLI11/issues/195
 [#199]: https://github.com/CLIUtils/CLI11/pull/199
+[#200]: https://github.com/CLIUtils/CLI11/pull/200
 
 ## Version 1.6.2: Help-all
 

README.md

@@ -194,17 +194,19 @@ app.add_set(option_name,
             set_of_possible_options,
             help_string="",
             default=false)
+app.add_mutable_set(... // Set can change later, keeps reference
 
 app.add_set_ignore_case(... // String only
-
+app.add__mutable_set_ignore_case(... // String only
 app.add_set_ignore_underscore(... // String only
-
+app.add__mutable_set_ignore_underscore(... // String only
 app.add_set_ignore_case_underscore(... // String only
+app.add_mutable_set_ignore_case_underscore(... // String only
 
 App* subcom = app.add_subcommand(name, description);
 ```
 
-An option name must start with a alphabetic character or underscore. For long options, anything but an equals sign or a comma is valid after that. Names are given as a comma separated string, with the dash or dashes. An option or flag can have as many names as you want, and afterward, using `count`, you can use any of the names, with dashes as needed, to count the options. One of the names is allowed to be given without proceeding dash(es); if present the option is a positional option, and that name will be used on help line for its positional form. If you want the default value to print in the help description, pass in `true` for the final parameter for `add_option` or `add_set`. The set options allow your users to pick from a set of predefined options; you can add an existing set if you need to modify the set later, or you can use an initializer list.
+An option name must start with a alphabetic character or underscore. For long options, anything but an equals sign or a comma is valid after that. Names are given as a comma separated string, with the dash or dashes. An option or flag can have as many names as you want, and afterward, using `count`, you can use any of the names, with dashes as needed, to count the options. One of the names is allowed to be given without proceeding dash(es); if present the option is a positional option, and that name will be used on help line for its positional form. If you want the default value to print in the help description, pass in `true` for the final parameter for `add_option` or `add_set`. The set options allow your users to pick from a set of predefined options, and you can use an initializer list directly if you like. If you need to modify the set later, use the `mutable` forms.
 
 On a C++14 compiler, you can pass a callback function directly to `.add_flag`, while in C++11 mode you'll need to use `.add_flag_function` if you want a callback function. The function will be given the number of times the flag was passed. You can throw a relevant `CLI::ParseError` to signal a failure.