Custom ways to invoke help

[h-2]

I need to be able to show the help page on ./myapp help in addition to (or instead of) ./myapp --help. How would I currently achieve that? Ideally there would be a nice mechanism for this and similar situations (e.g. ./myapp version), but I would also take a hacky solution 😬

[eseiler]

Here's a hacky solution:

#include <sharg/all.hpp>

int main(int argc, char const ** argv)
{
    // Or std::string if argv is `char` instead of `const char`
    static constexpr std::string_view call_help{"-h"};
    static constexpr std::string_view call_version{"--version"};
    
    std::vector const custom_argv = [&]()
    {
        std::vector result(argv, argv + argc);
        assert(argc > 0 && result.size() == static_cast<size_t>(argc));

        if (argc >= 2)
        {
            if (result[1] == std::string_view{"help"})
            {
                result[1] = call_help.data();
            }
            else if (result[1] == std::string_view{"version"})
            {
                result[1] = call_version.data();
            }
        }

        return result;
    }();

    sharg::parser parser{"my_app", argc, custom_argv.data()};
    parser.add_subsection("My Section");
    int val{};
    parser.add_option(val, sharg::config{.short_id = 'i', .long_id = "int", .description = "My description."});
    parser.parse();

    return 0;
}

We should at least discuss adding a C++-API for the parser constructor. Currently, the container's value_type needs to be char * or const char * 😬

[h-2]

Well, yes, that's a very hacky solution 😅 I had hoped for something that happens in the parser, and does not require fiddling with th args before. Especially sind fiddling is apparently so complicated.

I see two issues:

1. It should be possible to pass the arguments as a std::vector<std::string_view> or something generic.
2. It should be possible to provide user defined subcommands or options that lead to special formats like help or version. This is really very common behaviour. Even git (which is abundantly referenced in the subparser tutorial) has git help.

Regarding 1., I would like to suggest the constructor with config again. It would allow setting other options (like "auto-open-man-page") as well. If you have an std::vector<std::string_view> arguments member (or std::vector<std::string> — maybe more flexible), this can be conveniently initialised via (argv, argv + argc), so no additional members for argc and argv would need to be added to this object.

[eseiler]

1. It should be possible to pass the arguments as a std::vector<std::string_view> or something generic.

Yes, that's what I meant with C++-API :)
I am playing around with just accepting a std::span. Still need to properly test it, but it seems to work. The argc, argv ctor then just delegates to the span constructor.

I'll have to investigate a bit more how good std::span works, and probably add some overloads for converting a suitable range to a span, and some static_asserts to check that it's actually a range of char at some point.

Or just do a config like you suggested, but I wanted to try some smaller change first.

2. It should be possible to provide user defined subcommands or options that lead to special formats like help or version. This is really very common behaviour. Even git (which is abundantly referenced in the subparser tutorial) has git help.

Yes, but the difficult part is to do in such a way that the code doesn't get much more complex as it already is, while still being easy to use.

Could be adding something to the parser, like configuring aliases. Or maybe something with the subcommands, but then we would probably need to also store a pointer to the parent parser in addition to the subparser pointer.

Might already help if one was able to "manually" invoke a special parser.

Regarding 1., I would like to suggest the constructor with config again. It would allow setting other options (like "auto-open-man-page") as well. If you have an std::vector<std::string_view> arguments member (or std::vector<std::string> — maybe more flexible), this can be conveniently initialised via (argv, argv + argc), so no additional members for argc and argv would need to be added to this object.

IIRC, we decided that we want to do a config. But it's a rather big task...

BTW, do you have an idea for naming for the parser-config?

sharg::config is already used (we could of course rename that one, too).

sharg::parser_config, sharg::argument_config? Not sure.

[eseiler]

I played around with using a config, and I quite like the interface (as expected). And we can also just deprecate the old constructor. It'll also make the stuff like the man-page pr easier.

Regarding the help command, maybe it's a good idea to add aliases. My use case for that would be that I sometimes want to deprecate old cli options and this would make it easier. Maybe the ctor then just replaces the options with their alias.

So it would then be something like (add_option(sharg::config{.long_id = "help", .alias = "--help"});. Would then need to have some logic to not throw because help is a reserved word, and check that it is not a subcommand and the first argument (./app --something help shouldn't work).

[h-2]

BTW, do you have an idea for naming for the parser-config?

Hm, naming is hard. Maybe sharg::constructor or sharg::construct ? It's a bit weird, but also everbody will know that it contains arguments for constructing the main object (the parser). Or sharg::arguments or sharg::args because it contains the args? If there is no member template, the name can be omitted when used.

Regarding the help command, maybe it's a good idea to add aliases. My use case for that would be that I sometimes want to deprecate old cli options and this would make it easier. Maybe the ctor then just replaces the options with their alias.

This feature is not important for me.

So it would then be something like (add_option(sharg::config{.long_id = "help", .alias = "--help"});

This does not work for multiple reasons: .long_id = "help" already implies --help because of the way long_id works.
Also, the aliases for formats need to be detected on construction and not when .parse() is called, right? I think this was an unfortunate design choice, but probably not much can be done about it now.

The implication is that this feature needs to be implemented in the config. Possibilities are:

• non-generic solution: .common_options_as_subcommands = true (default false, transforms help, version and copyright into subcommands)
• "generic solution": .help_strings = {"-h", "--help"} (default shown, could be overwritten as = {"help"} or {"-h", "--help", "help"} which would make it a subcommand. Same for .version_strings ...

What I don't like about the second solution is that currently the dashes aren't exposed anywhere, and a subcommand is something fundamentally different from an option. Here we would be lumping it altogether as a collection of strings. But it seems to be the only solution that gives full flexibility.
For me, the non-generic solution would be absolutely sufficient.

[eseiler]

With #239, we accept std::vector<std::string> as input in addition to argc, argv.

So the hack would now be:

#include <sharg/all.hpp>

int main(int argc, char const ** argv)
{
    std::vector<std::string> arguments{argv, argv + argc};

    if (arguments.size() > 1u)
    {
        auto & first_argument = arguments[1];

        if (first_argument == "help")
        {
            first_argument = "--help";
        }
        else if (first_argument == "version")
        {
            first_argument = "--version";
        }
    }

    sharg::parser parser{"my_app", arguments};
    parser.add_subsection("My Section");
    int val{};
    parser.add_option(val, sharg::config{.short_id = 'i', .long_id = "int", .description = "My description."});
    parser.parse();

    return 0;
}

[h-2]

Yep, this works as a hacky solution... as long as no arguments have been provided to the top level parser before the help command—which is not super-likely before help, I guess.