[Argument Parser] Enable modification of default value display

[tloka]

Situation

My defaults are often calculated internally based on other parameters (e.g., a certain run mode such as "fast" or "accurate" which influences several internal parameters of the analysis), or even on properties of the input files (e.g., size of a database; read length).
Still, the user should be able to modify each single sub-parameter based on a certain mode.
Thus, with --mode fast --seeding-interval 10 the user would be able to select the fast mode which would calculate a seeding interval of let's say 8, but the user is still able to reset this value.

Problem

Due to the internal calculations, the default value displayed by the -h/--help command is not meaningful.

Example

tool -h
[...]
  --parameter  Parameter which is calculated automatically. Default: 0

Solution

Two possible solutions:

1.: Allow to turn off the display of default values for certain parameters (or is this already possible? didn't find a way on my own):

tool -h
[...]
  --parameter  Parameter which is calculated automatically.

2. Allow to manually specify default values (as std::string):

tool -h
[...]
  --parameter  Parameter which is calculated automatically. Default: Calculated based on the selected mode.

[marehr]

2020-04-20 Core-Meeting Resolution: We want this; We are not completely sure how to implement this. @smehringer is looking into possible implementations.

For a hacky workaround:

We had the idea that you can provide a custom type which behaves like a hybrid of std::optional and std::variant. It returns the string "Calculated based on the selected mode." by default if nothing is set and returns your real value if it was set by the argument parser or by yourself. Together with some "has_set_value" getter and maybe some std::ostream overloads for printing.

@smehringer wanted to hack something like this as a proof of concept.

[tloka]

Well, if this is non-trivial already let's make it even less trivial ;)
Why not creating a help_design_type that can be passed with each option and where several design decisions can be made on a per-option-level?
Possible things this could include:

• Flag to display default value
• Change default message
• Flag to display validator message (maybe even separated for normal and advanced help - for example when performing regex checks, this can be quite heavy for a standard help page).

However, I think in general it should be sufficient to make it possible to turn off default value and validator message. If I want some alternative text, I could simply put it into the description manually. Maybe this would be the easiest to implement!?

[smehringer]

Why would you want to hide the default?

[smehringer]

As a quick workaround for now, until we decide how to handle it you can do the following:

struct foo
{
    int value{-1};

    // this is needed to print the value
    friend std::ostream & operator<<(std::ostream & s, foo const & f)
    {
        if (f.value == -1) // default 
            return s << "My custom message";
        return s << f.value;
    }

    // this is needed for `value` to parsed like an regular int
    friend std::istream & operator>>(std::istream & s, foo & f)
    {
        return s >> f.value;
    }
};

// ...
    foo f{};
    myparser.add_option(bar, 'r', "bar", "foo option.");

This will print

    -r, --bar (foo)
          foo option. Default: My custom message.

[rrahn]

Some design drop:

parser.add_option(some_option, 's', "some", "descr", option_config.is_list().default_message("Whatever you like!").what_else_we_need('?')

So you can configure your option as you like. It is extendable, and does not imply any ordering on the arguments. Maybe we even use the | operator to be consistent with the other configs in SeqAn3. But when this is an external project that does not need to be.

[smehringer]

I added your proposal. Here are some possibilities.

[tloka]

Why would you want to hide the default?

I wouldn't, thought it would just be an easier solution. Definitely nicer to have a proper way to define the default message.
My first thoughts were pretty similar to solution 2 with a new config type.
However, I think I like solution 4 even more. Very generic and easy to extend for other things later (if desired). This is even nicer to use when having option_spec::DEFAULT and a validator, as to my understanding you will no longer need to explicitely type the DEFAULT state.

[smehringer]

Core Meeting 2022-03-22

Solution 1
+ is independent form the implementation. Works now.
- the user always has to do a strong type
- documentation is harder, because it is no directly related to the parser

Solution 2
- is ugly

Solution 3
- Is a little confusing because default message is not a validator
+ no extra function parameter

Solution 4
+ future proof for more stuff
- verbose
- a lot to implement with a config object

Solution 5
+ future proof for more stuff
+ easy to implement in a struct
+ reduces number of parameters
- API break (If we remove the old function, but they are easy to deprecate) -> sharg has no API, just "Break" API here, do seqan3::argument_parser : sharg::argument_parser and inherit ctors, add deprecated ctors

We want solution 5

Follow up decision:

• We will remove all the parameters except the option value. That way you can do

  arser.add_option(some_option, {.long_id = "some", 
                                 .description = "descr", 
                                 .default_message = "Whatever you like!",
                                 .validation = seqan3::input_file_valiator{},
                                 .specification = seqan3::option_spec::ADVANCED})

• What if the user wants to suppress the Default message?

  The default message is a std::optional<std::string>. If it is not set, the option value will be parsed for the default. If it is set but empty, no Default message will be printed.

• Since the parser is not API stable so far, we will break the API but when backporting it to seqan3 we will add the options and deprecate them there. (Done by inheriting from the parser)