v3.0.1

Cleanup of the docs markdown files

v3.0.0

📦 Release Notes – v3.0.0

This release of CPP-AP introduces new features, major improvements, and broad refactoring to enhance usability, consistency, and maintainability.

Parser Definitions

• Program name must now be provided via the argument_parser constructor (name parameter).
• Program name and version values are validated to disallow whitespace characters.
• Unified the ap::argument::default_positional and ap::argument::default_optional discriminator types into ap::default_argument.

Argument Parsing

• Positional arguments can now consume free values at arbitrary positions in the input, not only at the beginning of the command-line argument list.
• Parsing aligned to work with forward ranges only.
• Introduced unknown_policy with modes: fail (default), warn, ignore, and as_values.
  • Defines the way a parser should handle unknown argument flags.
  • Configurable via argument_parser::unknown_arguments_policy.

Argument Configuration

• Introduced ap::none_type as a valid argument value type. None-type arguments have restricted configuration options.
• Predefined --help, -h argument's value type changed from bool to ap::none_type.
• Added a new predefined --version, -v optional argument for printing a parser's version info.
• Default and implicit values can now be specified as collections instead of single items.
• Added variadic and range-based setters for default_values, implicit_values, and choices.
• Renamed the bypass_required argument attribute to suppress_arg_checks.
• Positional arguments now also have the nargs attribute.
• Greedy arguments:
  • Introduced a new greedy(bool) argument attribute.
  • Once a greedy argument starts being parsed, it consumes ALL values until its upper nargs limit is reached.

Argument Handling

• Positional arguments creation restricted to using a single name.
• Added an argument_parser::is_used(arg_name) method to check if an argument was provided.

Argument Groups

Argument groups provide a way to organize related arguments into logical sections and enforce group-wise requirements.

• Introduced an argument_group class with the following attributes:
  • required: at least one argument must be used.
  • mutually_exclusive: at most one argument can be used.
• Added an argument_parser::add_group(name) method.
• Extended the argument adding functionality to allow binding arguments to groups.
• Introduced a suppress_group_checks argument attribute.

Subparsers

Subparsers provide a way to build hierarchical command-line interfaces, where a top-level parser delegates parsing to its subcommands.

• Extended the argument_parser class with a collection of subparsers.
• Aligned argument parsing implementation to delegate parsing to a subparser if the first argument matches a subparser's name.
• Added an argument_parser::add_subparser(name) method.

Documentation & Cleanup

• Tutorial and inline documentation aligned with new API changes.
• Consolidated utility code into dedicated namespaces (ap::util, ap::action::util).
• Improved documentation comments and added a Utility section to generated docs.
• General code cleanup for readability and maintainability.
• Added logging_mode and ap_git demo projects.

v2.7.0

Added the parse_known_args and try_parse_known_args methods to the argument_parser class, which do not throw on unknown/unrecognized command-line arguments, but collect them and return them as a parsing result

v2.6.0

Modified the command-line tokenization logic to try to split unknown secondary flag arguments into multiple secondary argument flag tokens (one for each character of the unknown flag).

Example: If the program defines an argument with a secondary name v, then -vvv would be equivalent to -v -v -v, unless the program also defines a -vvv argument.

Additional:

• Added support for declaring the program version
• Optimized argument lookup during argument tokenization and parsing stages

v2.5.3

• Aligned the argument_name class to store both primary and secondary names as optionals
• Added the argument_name_discriminator enum for the purpose of argument initialization with specific name member being set
• Aligned the add_optional_argument and add_flag methods of argument_parser to take a discriminator member, specifying which name member should be set for the new argument

v2.5.2

Added the hidden attribute setter to the positional and optional argument classes.
If an argument is declared hidden, it will not be included in the program description generated by the argument parser.

v2.5.1

• Implemented type name demangling functionality
• Added the parametrized type_error class builder functions which use the type demangling functionality

v2.5.0

• Added the MODULE.bazel, BUILD.bazel and .bazelrc configuration files
• Aligned the check_version script to verify the Bazel module version
• Reverted the naming of the CMake library target back to cpp-ap instead of cpp-ap-2 to better match the naming of the Bazel module
• Updated the cpp-ap-demo submodule: added the Bazel configuration files to enable building the demo projects using Bazel
• Updated the demo workflow to build the demo projects using both CMake and Bazel and on both Linux and Windows platforms

v2.4.1

• Added the MSVC workflow
• Aligned the code to compile on Windows with the MSVC toolchain
• Deleted the doctest configuration test file

v2.4.0

Value handling improvement

Aligned argument value setting to use direct value_type object initialization from std::string values if possible (arguments, the value type of which cannot be constructed from std::string will use the istream>> operator as in previous versions)

NOTE: This fixes the issue, where passing a mulit-word optional argument's value, e.g.
./program --option "single value with spaces"
would result in storing only the first word of the value ("single" in this case)

Unknown flag handling alignment

In previous versions a command-line argument prefixed with -- or - and a value that did not match any of the specified arguments, it was treated as a value token. Currently a parsing_failre exception is thrown for such unknown argument flags by default, but the behavior can be changed to what it was in the previous versions by using the AP_UNKNOWN_FLAGS_AS_VALUES macro.

Other

• Modified the test building to compile each test file into a separate executable registered with CTest
• Corrected the argument value type requirements description in the tutorial document - previously the std::ostream& operator<< was used in the description instead of std::istream& operator>>