Is it possible to insert keywords in a command syntax?

[salmonb]

Hi,

I would like to know if it's possible to declare a command syntax like this one (for example):

rename <file> to <new_file>

How to declare the "to" mandatory keyword in that case?

Thanks for your excellent job!

[remkop]

What I would do is something like this:

@Command(name = "rename")
class Rename implements Runnable {
    @Parameters
    File file;

    @Option(names = "to", required = true)
    File new_file;

    public void run() { // business logic here
    }
}

This makes the to option mandatory. The following user input is valid:

rename <file> to <new_file>
rename to <new_file> <file>

This is invalid:

rename <file>
rename <file> <new_file>
rename to <new_file>

[salmonb]

Thanks. Almost perfect, except for the second user input that I would prefer to be invalid in my case:

rename to <new_file> <file>

However I would happily accept your solution if the usage was encouraging the preferred user input. Unfortunately this is not the case, as it shows:

Usage: rename to=<new_file> <file>

Is there a way to make it showing the preferred syntax?

Usage: rename <file> to=<new_file>

[salmonb]

I found another solution, still not perfect but closer to what I'm looking for:

@Command(name = "rename")
class Rename implements Runnable {

    enum ToKeyword {to}

    @Parameters(description = "File to rename.")
     File file;

    @Parameters(paramLabel = "to")
    ToKeyword to;

    @Parameters(description = "New file name.")
    File newFile;

    public void run() { // business logic here
    }
}

Regarding the user input, it's perfect as it only accepts the one I wish 😄

The only point is now with the usage:

Missing required parameters: '<file>', 'to', '<newFile>'
Usage: rename <file> to <newFile>
      <file>      File to rename.
      to
      <newFile>   New file name.

I would prefer to hide the 'to' parameter from the usage and only get:

Missing required parameters: '<file>', '<newFile>'
Usage: rename <file> to <newFile>
      <file>      File to rename.
      <newFile>   New file name.

Is it possible?

[remkop]

This is tricky... You want to include it in the synopsis, but exclude it from the error message and from the list of options-with-descriptions.

Both this approach and the earlier approach I suggested may require customizing the usage help message.
There are some examples of how to do this in the picocli-examples module, under customhelp and under synopsis.

One idea is to take your earlier comment:

Is there a way to make it showing the preferred syntax?

Usage: rename <file> to=<new_file>

I have pushed an example. Can you take a look?

[salmonb]

Thanks for the trick. Your solution is acceptable regarding my little example as the synopsis now shows the preferred syntax. 👍

Now I would like to use it for my real-world case, which is a bit more complex and I'm afraid it won't be easy to generalised.
Mainly because I'm using sub-commands and each sub-command may have its own keywords and syntax order.
So this would require writing a custom help factory for each sub-command (but I'm not sure it's actually possible in Picocli), or a big help factory at the command level that manages all these cases (which will quickly become complex).

I think a simpler solution is a mix between your solution with the custom help factory at the command level and my second proposition with the keyword declared as a single possible value enum. Because in that case I already completely control the order of the parameters and keywords using standard Picocli declaration for each of my sub-command. Also the synopsis is already good. Only the list of parameters shown above and below the synopsis should omit the keywords, and maybe this is something that can be written in a generic way with a help factory.

So is it possible to write such a help factory at the command level? Its function would be to remove all keyword parameters from the help usage (except for the synopsis which is already good like it is now). And a keyword parameter can be recognised in a generic way as being declared as an enum which contains only one value (like my ToKeyword example).

If this is achievable, I think it will be just perfect 😄

[remkop]

Okay, I added one more example that uses your preferred approach.

But you get the idea: you need to use the Help API to customize the usage message format.

Then you need some way to determine which parameters to hide and which to display. In the example I created a custom IExcluded interface, and I hide positional parameters whose type implements this interface from the parameter list in the usage help - and I don't hide them from the synopsis. Hopefully this is generic enough for your actual real-life use case.
If you need this to be different per command, you can obtain the CommandSpec from the PositionalParamSpec or OptionSpec, and apply separate logic per command in your custom Help class.

I hope this gives you enough pointers to get a start with the Help API and to figure out which methods to override to get the desired result. It may take some time to familiarize yourself with this API, but hopefully you can achieve the desired output.

Enjoy picocli! 😉

[salmonb]

Amazing! And it works with Sub commands like I expected 👍
That's getting very closed to what I want, thank you 😄

There are 2 little things I would like to add but I haven't found the way to do it:

• change the parameter color from orange to white in the synopsis when it's a keyword parameter
• remove the keyword parameter from the error message when listing the required parameters

But perhaps it's not customizable?

[salmonb]

I found how to do the first point (changing the parameter color in the synopsis) by overriding the method createDetailedSynopsisPositionalsText() in your MyHelpFactory:

class MyHelpFactory implements IHelpFactory {
    @Override
    public Help create(CommandLine.Model.CommandSpec commandSpec, Help.ColorScheme colorScheme) {
        return new Help(commandSpec, colorScheme) {
            @Override
            public String parameterList(List<PositionalParamSpec> positionalParams) {
                return super.parameterList(filter(positionalParams));
            }

            private List<PositionalParamSpec> filter(List<PositionalParamSpec> optionList) {
                List<PositionalParamSpec> shown = new ArrayList<>();
                for (PositionalParamSpec param : optionList) {

                    // exclude parameters whose type has the IExcluded marker interface
                    if (!IExcluded.class.isAssignableFrom(param.auxiliaryTypes()[0])) {
                        shown.add(param);
                    }
                }
                return shown;
            }

            @Override
            protected Ansi.Text createDetailedSynopsisPositionalsText(Collection<CommandLine.Model.ArgSpec> done) {
                Ansi.Text positionalParamText = ansi().new Text(0);
                List<PositionalParamSpec> positionals = new ArrayList<>(commandSpec.positionalParameters()); // iterate in declaration order
                if (hasAtFileParameter()) {
                    positionals.add(0, AT_FILE_POSITIONAL_PARAM);
                    AT_FILE_POSITIONAL_PARAM.messages(commandSpec.usageMessage().messages());
                }
                positionals.removeAll(done);
                for (PositionalParamSpec positionalParam : positionals) {
                    positionalParamText = concatPositionalText(" ", positionalParamText, colorScheme, positionalParam, parameterLabelRenderer());
                }
                return positionalParamText;
            }
            Ansi.Text concatPositionalText(String prefix, Ansi.Text text, Help.ColorScheme colorScheme, PositionalParamSpec positionalParam, IParamLabelRenderer parameterLabelRenderer) {
                if (!positionalParam.hidden()) {
                    Ansi.Text label = parameterLabelRenderer.renderParameterLabel(positionalParam, colorScheme.ansi(),
                            // Testing if the parameter is a keyword parameter
                            IExcluded.class.isAssignableFrom(positionalParam.auxiliaryTypes()[0]) ?
                                    colorScheme.commandStyles() :   // yes => will appear as white (like for commands)
                                    colorScheme.parameterStyles()); // no => will appear with standard parameter color
                    text = text.concat(prefix).concat(label);
                }
                return text;
            }
        };
    }
}

So basically I made a copy/paste of the original code of this method, but in concatPositionalText() I use the command styles (white color) for keyword parameters (the original code was using the parameter styles for all parameters). It works! Me happy 😃

Now for the last detail (removing the keyword parameter from the error message when listing the required parameters), I identified where the code was located: this loop in createMissingParameterMessage():

            for (PositionalParamSpec missing : missingList) {
                if (missing.arity().min > 0) {
                    names += sep + "'" + missing.paramLabel() + "'";
                    indices += sep + missing.index();
                    sep = ", ";
                    count++;
                }
            }

However it happens in a deep chain of calls of private methods, so I can't override the code like previously...
Is the only solution to patch your code (I was using Picocli as an external dependency so far)?

[remkop]

Hmm, ask yourself: is it okay for users not to specify to?

[salmonb]

No, but not typing to can be seen more like a syntax error than a missing parameter.
The idea was to treat these keyword parameters more like commands than standard parameters.

But no worries, and what you said also makes sense, it's just a matter of opinion.
I'm happy with what we already did, that's far good enough.

So I will now stop making your life difficult 😉
And thank you so much for having made Picocli 🙏

[remkop]

Great, glad to hear that!

Feel free to ask more questions whenever you want!
Enjoy picocli!
:-)