Java CLI Frameworks

package docsctl;

import java.util.concurrent.Callable;

import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.IExitCodeGenerator;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;

@Command(
    name = "docsctl",
    version = "docsctl 0.1.0",
    mixinStandardHelpOptions = true,
    description = "Search and publish this site's documentation.",
    exitCodeOnInvalidInput = 2,             // USAGE
    exitCodeOnExecutionException = 1,       // INTERNAL
    exitCodeListHeading = "%nExit codes:%n",
    exitCodeList = {
        "0:Success",
        "2:Usage error",
        "3:Validation problems found",
        "5:Confirmation required",
        "7:Authentication required"},
    subcommands = {Docsctl.Search.class, Docsctl.Validate.class, Docsctl.Publish.class})
public final class Docsctl implements Runnable {

    static final int VALIDATION = 3;
    static final int CONFIRMATION_REQUIRED = 5;

    @Option(names = "--json", scope = CommandLine.ScopeType.INHERIT, description = "Emit JSON on stdout.")
    boolean json;

    @Override
    public void run() {
        throw new CommandLine.ParameterException(new CommandLine(this), "Missing subcommand");
    }

    @Command(name = "search", description = "Search the documentation.",
             footer = "%nExample: docsctl search kalman --component irurueta-statistics --json")
    static final class Search implements Callable<Integer> {
        @Parameters(index = "0", paramLabel = "QUERY", description = "Words to look for.")
        String query;

        @Option(names = "--component", paramLabel = "NAME", description = "Restrict to one component.")
        String component;

        @Override
        public Integer call() {
            // data on stdout only; a real implementation would serialise with a JSON library
            System.out.printf("{\"query\":\"%s\",\"results\":[],\"schemaVersion\":1,\"total\":0}%n", query);
            return 0;
        }
    }

    @Command(name = "validate", description = "Validate the sources.")
    static final class Validate implements Runnable, IExitCodeGenerator {
        private int exitCode = 0;

        @Override
        public void run() {
            boolean problemsFound = true;        // stand-in for the real check
            if (problemsFound) {
                exitCode = VALIDATION;
                System.out.println("{\"ok\":false,\"schemaVersion\":1}");
            }
        }

        @Override
        public int getExitCode() {
            return exitCode;                     // picocli uses this after run() completes
        }
    }

    @Command(name = "publish", description = "Publish a component (destructive unless --dry-run).")
    static final class Publish implements Callable<Integer> {
        @Option(names = "--component", required = true, paramLabel = "NAME") String component;
        @Option(names = "--dry-run") boolean dryRun;
        @Option(names = {"--yes", "-y"}) boolean yes;

        @Override
        public Integer call() {
            if (dryRun) {
                System.out.println("{\"dryRun\":true,\"schemaVersion\":1}");
                return 0;
            }
            if (!yes) {
                System.err.println("docsctl: publish needs confirmation; re-run with --yes or use --dry-run.");
                return CONFIRMATION_REQUIRED;    // the returned Integer becomes the exit code
            }
            return 0;
        }
    }

    public static void main(String[] args) {
        System.exit(new CommandLine(new Docsctl()).execute(args));
    }
}

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.13.0</version>
  <configuration>
    <annotationProcessorPaths>
      <path>
        <groupId>info.picocli</groupId>
        <artifactId>picocli-codegen</artifactId>
        <version>4.7.7</version>
      </path>
    </annotationProcessorPaths>
    <compilerArgs>
      <arg>-Aproject=${project.groupId}/${project.artifactId}</arg>
    </compilerArgs>
  </configuration>
</plugin>

native-image -jar target/docsctl-0.1.0.jar docsctl

hyperfine --warmup 3 'java -jar target/docsctl-0.1.0.jar --version' './docsctl --version'

package docsctl;

import org.springframework.shell.core.command.annotation.Argument;
import org.springframework.shell.core.command.annotation.Command;
import org.springframework.shell.core.command.annotation.Option;
import org.springframework.stereotype.Component;

/** Your own service bean; returns the JSON document of the docsctl contract. */
interface DocsSearch {
    String searchJson(String query, String component, int limit);
}

@Component
class SearchCommands {

    private final DocsSearch docs;

    SearchCommands(DocsSearch docs) {
        this.docs = docs;
    }

    @Command(name = "search", description = "Search the documentation.", group = "docs",
            help = "Example: docsctl search --component=irurueta-statistics kalman")
    public String search(
            @Argument(index = 0, description = "Words to look for") String query,
            @Option(longName = "component", description = "Restrict to one component", defaultValue = "") String component,
            @Option(longName = "limit", description = "Maximum results, 1 to 100", defaultValue = "10") int limit) {
        return docs.searchJson(query, component, limit); // the returned value is printed
    }
}

package docsctl;

import java.nio.file.Path;

import org.jline.reader.EndOfFileException;
import org.jline.reader.LineReader;
import org.jline.reader.LineReaderBuilder;
import org.jline.reader.UserInterruptException;
import org.jline.terminal.Terminal;
import org.jline.terminal.TerminalBuilder;

/** {@code docsctl shell}: an optional interactive loop; agents keep using {@code docsctl search --json}. */
public final class Repl {

    public static void main(String[] args) throws Exception {
        try (Terminal terminal = TerminalBuilder.builder().system(true).build()) {
            String type = terminal.getType();
            if (Terminal.TYPE_DUMB.equals(type) || Terminal.TYPE_DUMB_COLOR.equals(type)) {
                System.err.println("docsctl: shell needs a terminal; use `docsctl search --json -- QUERY` instead.");
                System.exit(2);
            }
            LineReader reader = LineReaderBuilder.builder()
                    .terminal(terminal)
                    .appName("docsctl")
                    .variable(LineReader.HISTORY_FILE, Path.of(System.getProperty("user.home"), ".docsctl_history"))
                    .build();
            while (true) {
                String query;
                try {
                    query = reader.readLine("search> ").strip();
                } catch (UserInterruptException e) { // Ctrl+C: drop the current line
                    continue;
                } catch (EndOfFileException e) {     // Ctrl+D: leave the loop
                    break;
                }
                if (query.isEmpty()) {
                    continue;
                }
                if (query.equals("quit")) {
                    break;
                }
                terminal.writer().println(search(query));
                terminal.flush();
            }
        }
    }

    private static String search(String query) {
        return "results for: " + query; // call the same code as `docsctl search`
    }
}