Class CommandLine

java.lang.Object
com.codename1.cli.CommandLine
public final class CommandLine extends Object

Parses a command line into an annotated command and runs it.

A command is a class annotated CommandLine.Command that implements Runnable or java.util.concurrent.Callable<Integer>. Its fields annotated CommandLine.Option and CommandLine.Parameters receive the arguments:

@Command(name = "greet", mixinStandardHelpOptions = true, version = "greet 1.0",
        description = "Prints a greeting.")
public class Greet implements Runnable {
    @Option(names = {"-n", "--count"}, description = "How many times.",
            defaultValue = "1")
    private int count;

    @Parameters(paramLabel = "<name>", description = "Who to greet.")
    private String name;

    public void run() {
        for (int i = 0; i < count; i++) {
            System.out.println("Hello " + name);
        }
    }
}

The names follow picocli, so a picocli command usually needs only its imports changed. Unlike picocli nothing is read by reflection: the build reads the annotations and generates the parser's bindings, so a mistake in a declaration is a build error, and the command runs the same on the JVM and as a native executable.

The build also writes main. With one top-level command it runs that command; with several, they become the subcommands of one named after the application. In a backend that also has controllers, the server is the serve subcommand and the command line with no arguments still starts it.

Exit codes: 0 for success, the command's own code from a Callable, 1 when the command throws, 2 for a command line that does not parse.

  • Field Details

    • USAGE_ERROR

      public static final int USAGE_ERROR
      The exit code for a command line that does not parse.
      See Also:

    • SERVED

      public static final int SERVED
      What serve(String, CommandSpec[], CommandLine.Server, String[]) answers when the server ran rather than a command. Every int a command can return is a valid exit code, negative ones included, so the marker is the one value whose exit status is indistinguishable from 0 anyway (Integer.MIN_VALUE & 0xff is 0).
      See Also:

    • EXECUTION_ERROR

      public static final int EXECUTION_ERROR
      The exit code for a command that threw.
      See Also:

  • Constructor Details

    • CommandLine

      public CommandLine(CommandSpec spec)
      Creates a command line for the command spec describes.

  • Method Details

    • getCommandSpec

      public CommandSpec getCommandSpec()
      The model of the top-level command.

    • setOut

      public CommandLine setOut(PrintStream out)
      Where help, version and the command's output are printed. Defaults to System.out.

    • setErr

      public CommandLine setErr(PrintStream err)
      Where errors are printed. Defaults to System.err.

    • execute

      public int execute(String... args)
      Parses args, runs the command they name, and answers the exit code. Never throws: a command line that does not parse prints the error and the usage and answers USAGE_ERROR; a command that throws prints the error and answers EXECUTION_ERROR.

    • usage

      public void usage()
      Prints the command's usage help to System.out.

    • usage

      public static void usage(CommandSpec command, PrintStream stream)
      Prints the usage help of command to stream.

    • run

      public static int run(String appName, CommandSpec[] commands, String[] args)

      The entry point the build generates for an application whose top-level commands are commands: runs the command line and answers the exit code.

      One command is the top level itself; several become the subcommands of a group named appName.

    • serve

      public static int serve(String appName, CommandSpec[] commands, CommandLine.Server server, String[] args) throws Exception

      The entry point the build generates for a backend. With no arguments it starts the server, as a backend always has. Otherwise the server is the serve subcommand beside commands.

      When there are no commands, only -h/--help is recognized, and any other argument starts the server as before, so an existing deployment that passes arguments a backend used to ignore keeps working.

      Returns

      the exit code, or SERVED when the server ran and the process should end the way a server's does.

      Throws:
      Exception