CLI11 Versions Save

This version focuses on cleaning up deprecated functionality, and some minor default changes. The config processing is TOML compliant now. Atomics and complex numbers are directly supported, along with other container improvements. A new version flag option has finally been added. Subcommands are significantly improved with new features and bugfixes for corner cases. This release contains a lot of backend cleanup, including a complete overhaul of the testing system and single file generation system.

• Built-in config format is TOML compliant now #435
  • Support multiline TOML #528
  • Support for configurable quotes #599
  • Support short/positional options in config mode #443
• More powerful containers, support for %% separator #423
• Support atomic types #520 and complex types natively #423
• Add a type validator CLI::TypeValidator<TYPE> #526
• Add a version flag easily #452, with help message #601
• Support ->silent() on subcommands. #529
• Add alias section to help for subcommands #545
• Allow quotes to specify a program name #605
• Backend: redesigned MakeSingleFiles to have a higher level of manual control, to support future features. #546
• Backend: moved testing from GTest to Catch2 #574
• Bugfix: avoid duplicated and missed calls to the final callback #584
• Bugfix: support embedded newlines in more places #592
• Bugfix: avoid listing helpall as a required flag #530
• Bugfix: avoid a clash with WINDOWS define #563
• Bugfix: the help flag didn't get processed when a config file was required #606
• Bugfix: fix description of non-configurable subcommands in config #604
• Build: support pkg-config #523

Converting from CLI11 1.9:

• Removed deprecated set commands, use validators instead. #565
• The final "defaulted" bool has been removed, use ->capture_default_str() instead. Use app.option_defaults()->always_capture_default() to set this for all future options. #597
• Use add_option on a complex number instead of add_complex, which has been removed.

This is a patch version that backports fixes from the development of 2.0.

• Support relative inclusion #475
• Fix cases where spaces in paths could break CMake support #471
• Fix an issue with string conversion #421
• Cross-compiling improvement for Conan.io #430
• Fix option group default propagation #450
• Fix for C++20 #459
• Support compiling with RTTI off #461

Config file handling was revamped to fix common issues, and now supports reading TOML.

Adding options is significantly more powerful with support for things like std::tuple and std::array, including with transforms. Several new configuration options were added to facilitate a wider variety of apps. GCC 4.7 is no longer supported.

• Config files refactored, supports TOML (may become default output in 2.0) #362
• Added two template parameter form of add_option, allowing std::optional to be supported without a special import #285
• string_view now supported in reasonable places #300, #285
• immediate_callback, final_callback, and parse_complete_callback added to support controlling the App callback order #292, #313
• Multiple positional arguments maintain order if positionals_at_end is set. #306
• Pair/tuple/array now supported, and validators indexed to specific components in the objects #307, #310
• Footer callbacks supported #309
• Subcommands now support needs (including nameless subcommands) #317
• More flexible type size, more useful add_complex #325, [#370][]
• Added new validators CLI::NonNegativeNumber and CLI::PositiveNumber #342
• Transform now supports arrays #349
• Option groups can be hidden #356
• Add CLI::deprecate_option and CLI::retire_option functions #358
• More flexible and safer Option default_val [#387][]
• Backend: Cleaner type traits #286
• Backend: File checking updates [#341][]
• Backend: Using pre-commit to format, checked in GitHub Actions #336
• Backend: Clang-tidy checked again, CMake option now CL11_CLANG_TIDY #390
• Backend: Warning cleanup, more checks from klocwork #350, Effective C++ #354, clang-tidy #360, CUDA NVCC #365, cross compile #373, sign conversion #382, and cpplint #400
• Docs: CLI11 Tutorial now hosted in the same repository #304, #318, #374
• Bugfix: Fixed undefined behavior in checked_multiply #290
• Bugfix: ->check() was adding the name to the wrong validator #320
• Bugfix: Resetting config option works properly #301
• Bugfix: Hidden flags were showing up in error printout #333
• Bugfix: Enum conversion no longer broken if stream operator added #348
• Build: The meson build system supported #299
• Build: GCC 4.7 is no longer supported, due mostly to GoogleTest. GCC 4.8+ is now required. #160
• Build: Restructured significant portions of CMake build system #394

Converting from CLI11 1.8:

• Some deprecated methods dropped
  • add_set* should be replaced with ->check/->transform and CLI::IsMember since 1.8
  • get_defaultval was replaced by get_default_str in 1.8
• The true/false 4th argument to add_option is expected to be removed in 2.0, use ->capture_default_str() since 1.8

Set handling has been completely replaced by a new backend that works as a Validator or Transformer. This provides a single interface instead of the 16 different functions in App. It also allows ordered collections to be used, custom functions for filtering, and better help and error messages. You can also use a collection of pairs (like std::map) to transform the match into an output. Also new are inverted flags, which can cancel or reduce the count of flags, and can also support general flag types. A new add_option_fn lets you more easily program CLI11 options with the types you choose. Vector options now support a custom separator. Apps can now be composed with unnamed subcommand support. The final bool "defaults" flag when creating options has been replaced by ->capture_default_str() (ending an old limitation in construction made this possible); the old method is still available but may be removed in future versions.

• Replaced default help capture: .add_option("name", value, "", True) becomes .add_option("name", value)->capture_default_str() #242
• Added .always_capture_default() #242
• New CLI::IsMember validator replaces set validation #222
• IsMember also supports container of pairs, transform allows modification of result #228
• Added new Transformers, CLI::AsNumberWithUnit and CLI::AsSizeValue #253
• Much more powerful flags with different values #211, general types #235
• add_option now supports bool due to unified bool handling #211
• Support for composable unnamed subcommands #216
• Reparsing is better supported with .remaining_for_passthrough() #265
• Custom vector separator using ->delimiter(char) #209, #221, #240
• Validators added for IP4 addresses and positive numbers #210 and numbers #262
• Minimum required Boost for optional Optionals has been corrected to 1.61 #226
• Positionals can stop options from being parsed with app.positionals_at_end() #223
• Added validate_positionals #262
• Positional parsing is much more powerful #251, duplicates supported []#247]
• Validators can be negated with ! #230, and now handle tname functions #228
• Better enum support and streaming helper #233 and #228
• Cleanup for shadow warnings #232
• Better alignment on multiline descriptions #269
• Better support for aarch64 #266
• Respect BUILD_TESTING only if CLI11 is the main project; otherwise, CLI11_TESTING must be used #277
• Drop auto-detection of experimental optional and boost::optional; must be enabled explicitly (too fragile) #277 #279

Converting from CLI11 1.7:

• .add_option(..., true) should be replaced by .add_option(...)->capture_default_str() or app.option_defaults()->always_capture_default() can be used
• app.add_set("--name", value, {"choice1", "choice2"}) should become app.add_option("--name", value)->check(CLI::IsMember({"choice1", "choice2"}))
• The _ignore_case version of this can be replaced by adding CLI::ignore_case to the argument list in IsMember
• The _ignore_underscore version of this can be replaced by adding CLI::ignore_underscore to the argument list in IsMember
• The _ignore_case_underscore version of this can be replaced by adding both functions listed above to the argument list in IsMember
• If you want an exact match to the original choice after one of the modifier functions matches, use ->transform instead of ->check
• The _mutable versions of this can be replaced by passing a pointer or shared pointer into IsMember
• An error with sets now produces a ValidationError instead of a ConversionError

This version provides a quick patch for a (correct) warning from GCC 8 for the windows options code.

• Fix for Windows style option parsing #201
• Improve add_subcommand when throwing an exception #204
• Better metadata for Conan package #202

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. 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
• Dropped the mostly undocumented short_circuit property, as help flag parsing is a bit more complex, and the default callback behavior of options now works properly. #179
• Use the standard BUILD_TESTING over CLI11_TESTING if defined (CLI11_TESTING may eventually be removed) #183
• Cleanup warnings #191
• Remove deprecated names: set_footer, set_name, set_callback, and set_type_name. Use without the set_ instead. #192

Converting from CLI11 1.6:

• ->short_circuit() is no longer needed, just remove it if you were using it - raising an exception will happen in the proper place now without it.
• ->add_set* becomes ->add_mutable_set* if you were using the editable set feature
• footer, name, callback, and type_name must be used instead of the set_* versions (deprecated previously).

This version fixes some formatting bugs with help-all. It also adds fixes for several warnings, including an experimental optional error on Clang 7. Several smaller fixes.

• Fixed help-all formatting #163
  • Printing help-all on nested command now fixed (App)
  • Missing space after help-all restored (Default formatter)
  • More detail printed on help all (Default formatter)
  • Help-all subcommands get indented with inner blank lines removed (Default formatter)
  • detail::find_and_replace added to utilities
• Fixed CMake install as subproject with CLI11_INSTALL flag. #156
• Fixed warning about local variable hiding class member with MSVC #157
• Fixed compile error with default settings on Clang 7 and libc++ #158
• Fixed special case of --help on subcommands (general fix planned for 1.7) #168
• Removing an option with links #179

This version provides a few fixes for special cases, such as mixing with Windows.h and better defaults for systems like Hunter. The one new feature is the ability to produce "branded" single file output for providing custom namespaces or custom macro names.

• Added fix and test for including Windows.h #145
• No longer build single file by default if main project, supports systems stuck on Python 2.6 #149, #151
• Branding support for single file output #150

Added a new formatting system #109. You can now set the formatter on Apps. This has also simplified the internals of Apps and Options a bit by separating most formatting code.

• Added CLI::Formatter and formatter slot for apps, inherited.
• FormatterBase is the minimum required.
• FormatterLambda provides for the easy addition of an arbitrary function.
• Added help_all support (not added by default).

Changes to the help system (most normal users will not notice this):

• Renamed single_name to get_name(false, false) (the default).
• The old get_name() is now get_name(false, true).
• The old get_pname() is now get_name(true, false).
• Removed help_* functions.
• Protected function _has_help_positional removed.
• format_help can now be chained.
• Added getters for the missing parts of options (help no longer uses any private parts).
• Help flags now use new short_circuit property to simplify parsing. #121

New for Config file reading and writing #121:

• Overridable, bidirectional Config.
• ConfigINI provided and used by default.
• Renamed ini to config in many places.
• Has config_formatter() and get_config_formatter().
• Dropped prefix argument from config_to_str.
• Added ConfigItem.
• Added an example of a custom config format using nlohmann/json. #138

Validators are now much more powerful #118, all built in validators upgraded to the new form:

• A subclass of CLI::Validator is now also accepted.
• They now can set the type name to things like PATH and INT in [1-4].
• Validators can be combined with & and |.
• Old form simple validators are still accepted.

Other changes:

• Fixing parse(args)'s args setting and ordering after parse. #141
• Replaced set_custom_option with type_name and type_size instead of set_custom_option. Methods return this. [#136]
• Dropped set_ on Option's type_name, default_str, and default_val. [#136]
• Removed set_ from App's failure_message, footer, callback, and name. [#136]
• Fixed support N<-1 for type_size. #140
• Added ->each() to make adding custom callbacks easier. #126
• Allow empty options add_option("-n",{}) to be edited later with each #142
• Added filter argument to get_subcommands, get_options; use empty filter {} to avoid filtering.
• Added get_groups() to get groups.
• Better support for manual options with get_option, set_results, and empty. #119
• lname and sname have getters, added const get_parent. #120
• Using add_set will now capture L-values for sets, allowing further modification. #113
• Dropped duplicate way to run get_type_name (get_typeval).
• Removed requires in favor of needs (deprecated in last version). #112
• Const added to argv. #126

Backend and testing changes:

• Internally, type_name is now a lambda function; for sets, this reads the set live. #116
• Cleaner tests without app.reset() (and reset is now clear). #141
• Better CMake policy handling. #110
• Includes are properly sorted. #120
• Testing (only) now uses submodules. #111

This version fixes the optional search in the single file version; some macros were not yet defined when it did the search. You can define the CLI11_*_OPTIONAL macros to 0 if needed to eliminate the search.