ParserBuilder

[rsore]

Description

In this development branch I have implemented a ParserBuilder class, as proposed in #35.

The previous approach of passing all configuration options as template parameters directly to the Parser class led to complex, unreadable code, especially as the number of options and flags grew. By introducing ParserBuilder, the user can now build the parser step-by-step, resulting in cleaner and more maintainable code. This change simplifies parser creation without sacrificing compile-time safety and flexibility. The builder pattern not only makes the code more readable but also allows users to conditionally or incrementally add flags and options, making it more adaptable to dynamic configurations.

An example use-case can be seen below:

CLArgs::Parser parser = CLArgs::ParserBuilder{}
                                .add_program_description<"Program description">()
                                .add_flag<VerboseFlag>()
                                .add_option<ConfigOption>()
                                .build();

The ParserBuilder uses compile-time template instantiation to incrementally assemble the parser's configuration. Each add_flag, add_option, and add_program_description call modifies the parser type at compile time, ensuring that type safety is maintained throughout the process. This approach avoids runtime overhead while making the parser-building process more flexible.

The Parser type that is returned is the same as before, and the same API applies. As you can see, I have also added the notion of a "program description," which is an optional string the user can provide. If added, the generated help message will include this description.

A key advantage of this new builder pattern is the ability to conditionally add flags or options based on the target environment. For example, users can add platform-specific options or flags, such as enabling specific flags only for Windows builds, as shown below:

auto builder = CLArgs::ParserBuilder{}
                   .add_flag<VerboseFlag>()
                   .add_option<ConfigOption>();
#ifdef _WIN32
    builder = builder.add_flag<WindowsSpecificFlag>();
#endif
CLArgs::Parser parser = builder.build();

Related Issues

Closes #35.

How Has This Been Tested?

I have adapted existing tests to build with the new parser API, and they all pass. I have also introduced new unit tests, specific for the builder. Finally, manual and visual testing has been performed throughout development.

Further considerations

Though this new builder API does make the user-side parser definition more readable, I have a growing concern with regards to the Parser class definition. Consider the simple program() method:

template <CLArgs::CmdFlag... Flags, CLArgs::CmdOption... Options, CLArgs::StringLiteral ProgramDescription>
std::string_view
CLArgs::Parser<CLArgs::CmdFlagList<Flags...>, CLArgs::CmdOptionList<Options...>, ProgramDescription>::program() const noexcept
{
    return program_;
}

The current growth of template parameters is becoming unwieldy, particularly when considering future features such as positional arguments (#8), sub-commands, and validators (#4). To manage this complexity, I propose encapsulating the configuration into a ParserConfig struct. This would store all parameters as static members, simplifying the function signatures and improving readability. While there is a risk that the complexity could simply be shifted to this struct, the benefits of a centralized configuration object could outweigh that, especially as we introduce more features.

[github-actions]

clang-tidy review says "All clean, LGTM! 👍"