Filter subcommands at runtime when declared with annotations.

[MarkoMackic]

Hi, is there currently a way to filter subcommands at runtime if they are declared with annotations ?

@Command(name="xx", subcommands={YY.class, CC.class, AA.class})
class XX implements Callable<Integer>
{
   
    // this is API example of my implementation, though I don't really like it, it's not strongly typed, but it should be something in this form.
 
    public static Boolean picocliFilterSubcommand(Class subcommand)
    {
          if(Boolean.valueOf(System.getProperty("DISABLE_CC_SUBCOMMAND"))
             return subcommand == CC.class;
    }
   
    @Override
    public Integer call() throws Exception
    {
    }
}

Here is that PR in my fork implementing this, but I think there should be a way to more properly implement this

MarkoMackic#1

[remkop]

Do you mean to hide subcommands in the usage help message dynamically, or to actually remove subcommands (so users cannot invoke them)?

If the latter, isn’t it more convenient to use the programmatic API to only add the subcommands that are needed once this can be determined at runtime?

[MarkoMackic]

nope, the latter one, sure, programmatic API could do here, I'm aware of that, but it would be great if you could combine easiness of annotations API, and add some programmatic control over it. And as of first question, completely remove access to command, not just the help message.

[MarkoMackic]

Also I think many users who use the library chose annotations API for it's simplicity, and if a large codebase depend on it, rewriting it to programmatic is a huge job. I don't know if many people need this, but certainly it wouldn't affect them for the worse.

[remkop]

Thanks for the clarification. Ok, not sure when I will be able to get to implementing this, but first, let's take a look at what the API for this should look like.

You sketched out a solution involving filters that would allow you to accomplish this, but would you be open to a different approach? I was thinking of something like this:

@Command(name="xx", subcommands={YY.class, CC.class, AA.class})
class XX implements Callable<Integer> {

    public static void main(String... args) {
        CommandLine cmd = new CommandLine(new XX());
        if (Boolean.getBoolean("DISABLE_CC_SUBCOMMAND")) {
            cmd.getCommandSpec().removeSubcommand("cc"); // name or alias of the CC command
        }
        cmd.execute(args);
    }

    ...
}

Currently, the map returned by CommandSpec::subcommands is an unmodifiable map, so we would need to make some changes, like adding the above removeSubcommand method, to make this possible. (That may actually be the only change that is needed.)

Thoughts?

[MarkoMackic]

Well I think it needs to be recursive ( subcommands can also exclude their subcommands ) and also code for exclusion should be in the command that does some exclusion process , let's say you're excluding something from CC which is subcommand of XX you'd write your exclusion code in CC . As I've understood the code, whole commands tree is built at start, so filtering methods must be static, as nothing is initialized, but still could be context aware. Your API proposal could work with nested subcommands but it's centralized and not straight forward, and gets harder when you're going deeper, excluding subcommands of subcommands of subcommands, but in context aware approach, all code is localized to command.

Thoughts?

[remkop]

If I understand correctly, you are looking for a way to invoke custom logic during the parsing process: as soon as subcommand CC is recognized on the command line, then the custom "preprocessing" logic for that subcommand would be invoked (in our example to dynamically remove some sub-subcommand) before subsequent command line parameters are parsed. This preprocessing logic should be able to do more than just remove sub-subcommands, it would be nice to make it more generic.

Okay, that is an interesting idea, and reminds me a bit of the "parameter preprocessor" idea proposed in #1217 (comment), but applied to CommandSpec instead of ArgSpec.

Note that we will still need to have a removeSubcommand method, regardless of whether we call it from the main method or from our hypothetical preprocessor.

For the purposes of your use case, I believe adding a removeSubcommand method will allow you to create a solution: while the details of #1217 (comment) are not yet fleshed out, this would give you the possibility to customize the subcommands from the main method. This solution is not perfect, but better than creating the full command/subcommand hierarchy using the programmatic API.

Then, by applying the preprocessor proposed in #1217 (comment) to Commands as well, we can provide a callback that is invoked during parsing for each commands, which I believe satisfies your second point.

Thoughts?

[MarkoMackic]

Actually I thought more about invoking custom logic/s ( these can be distributed, every Command class could have this logic for it's subcommands which are again Command and they can have their logic for their subcommands ) before parser actually does anything, the logic would be invoked in annotations processing stage ( I think I understood codebase correctly, first the tree is built and then the parser comes to stage ), because anyways you can't rely on app internal state because there is no internal state, you can rely on state provided by JVM, or some config file ( the state that's existent before main is invoked ), so there doesn't need to be logic for when command is initialized. The static filtering would probably be better due to let's say man page generation, you'd have a clear tree, as you have it now, and than dump it in according format. But I'm ok with filtering at command init level too ( I think this is what you're saying in the comment above if I understood correctly)

[remkop]

Ok, that is also an interesting idea, to do this at model-building time. Note that there are 2 ways the model can be built from the annotations: with reflection (this is what happens when you call new CommandLine(myapp), or with the annotation processor. The annotation processor is actually quite limited, it will not be able to instantiate classes and execute custom code - this is due to limitations of the Java annotation processor.

At the moment I feel that creating a preprocessor interface that gets called during the parse stage (as suggested in #1217 (comment)) would be more generally useful since it can be used to modify the model (like in your use case), but also to modify the command line arguments or reconfigure the parser or various other use cases.

[remkop]

Would work something like this:

@Command (name = "cc", preprocessor = MyProc.class)
class CC ...

...where MyProc implements the interface defined in #1217.

The preprocessor gets invoked after the command was recognized, before parsing any other arguments.

[MarkoMackic]

I like the idea, so we could discuss the initial structure of ICommandPreprocessor interface and I'd be glad to do some work about it.

[remkop]

I was thinking to rename the interface proposed in #1217 to IPreprocessor and use it for both commands and options/positional parameters.

Thoughts?

[MarkoMackic]

Well if you have same generic method for both you could put it in a single interface. But if preprocessors are per annotation, I'd have them split and maybe expose functions more related to preprocessing current type ( @Option, @Command, .. ). That would probably improve the UX