Add support for globally registering color schemes

[bobtiernay-okta]

Right now it doesn't appear to be possible to globally set anCommandLine.Help.ColorScheme and have this be consistently applied to an application. A common example is when using subcommands and an HelpCommand. If the parent command modifies the color scheme, this doesn't propagate to the help command.

As a workaround, one can do something similar to:

    static {
        // Color scheme
        System.setProperty("picocli.color.options", "fg(249)");
        System.setProperty("picocli.color.parameters", "fg(249)");
    }

But this is less than ideal from a localization and overriding perspective.

[remkop]

Thanks for raising this.

To clarify, is it all of the following methods that do not behave as expected?

CommandLine::usage(Object, PrintStream, ColorScheme); // static
CommandLine::usage(PrintStream, ColorScheme);
CommandLine::usage(PrintWriter, ColorScheme);

Can you please show steps to reproduce the issue?

[bobtiernay-okta]

I think the main issue I'm hitting is that I cannot globally centralize the ColorScheme in the CommandLine itself. e.g.

@Command(
        name = "test",
        mixinStandardHelpOptions = true,
        subcommands = {
                HelpCommand.class, // myCustomColorScheme below doesn't propagate here
                MyCommand.class})
public class AllCommand extends AbstractCommand {

    @Override
    public Status call() {
        commandSpec.commandLine()
                .usage(System.out, myCustomColorScheme);

        return super.call();
    }

doesn't result in a consistent theme because HelpCommand is programmed as follows:

        /** Invokes {@link #usage(PrintStream, Help.Ansi) usage} for the specified command, or for the parent command. */
        public void run() {
...
            } else {
                parent.usage(out, ansi);
            }
        }

where CommandLine#usage is as follows:

public void usage(PrintStream out, Help.Ansi ansi) { usage(out, Help.defaultColorScheme(ansi)); }

and Help.defaultColorScheme above is hardcoded.

[remkop]

Thanks for the clarification. I understand the problem now.

[remkop]

I think the problem is that in the convenience methods (run, call, invoke), there is support for specifying an Ansi object but not a ColorScheme.

To support this, the static CommandLine::run, CommandLine::call and CommandLine::invoke methods need to change, and AbstractHandler needs a useColorScheme(ColorScheme) method (similar to the current useAnsi method).

If the above is added, it should be possible for an application to have a consistent color scheme everywhere in the command hierarchy by simply calling:

public static void main(String[] args) {
    ColorScheme myColorScheme = createColorScheme(); 
    CommandLine.run(new MyApp(), args, myColorScheme);
}

[remkop]

Additionally, a new interface IHelpCommandInitializable2 needs to be added that takes a ColorScheme instead of an Ansi object so that help commands can be initialized with the color scheme of the parent...

    public static interface IHelpCommandInitializable2 {
        /** Initializes this object with the information needed to implement a help command that provides usage help for other commands.
         * @param helpCommandLine the {@code CommandLine} object associated with this help command. Implementors can use
         *                        this to walk the command hierarchy and get access to the help command's parent and sibling commands.
         * @param scheme the color scheme to use
         * @param out the stream to print the usage help message to
         * @param err the error stream to print any diagnostic messages to, in addition to the output from the exception handler
         */
        void init(CommandLine helpCommandLine, Help.ColorScheme scheme, PrintStream out, PrintStream err);

[remkop]

The existing convenience methods (run, call, invoke) now support color schemes in addition to Ansi values. The built-in HelpCommand now implements a new interface ,IHelpCommandInitializable2, which allows callers to initialize the help command with a color scheme instead of just an Ansi enum value.

Please verify.

[remkop]

I may partially revert this commit.
The new recommended API will likely look like this:

CommandLine cmd  = new CommandLine(new MyRunnable())
    .setOut(createOutPrintWriter())       // System.out by default
    .setErr(createErrPrintWriter())       // System.err by default
    .setColorScheme(createColorScheme()); // default color scheme by default
int exitCode = cmd.execute(args);
//System.exit(exitCode);

I will likely deprecate the run, call and invoke overloaded methods that take PrintStreams and Ansi objects, and only leave the minimal versions that just take the user object and the arguments. The methods that I just added that take a ColorScheme will be removed in favor of the above recommended API.