Package io.github.wankdanker.clyops

Class Cli

java.lang.Object
io.github.wankdanker.clyops.Cli
public class Cli extends Object
Declarative, one-line-per-option CLI parsing: validation, help text, a JSON schema of the interface, config files, environment variables and shell completion. Behavior follows spec/SPEC.md in https://github.com/wankdanker/clyops. 

 Cli cli = new Cli("mytool");
 cli.arg("input", "Input file", "", "path");
 cli.opt("PORT", "port", "p", "8080", "Server port", "Network", "port");
 cli.opt("VERBOSE", "verbose", "v", "flag", "Verbose output");
 Values v = cli.run(args);
 System.out.println(v.getString("input") + " " + v.getInt("PORT") + " " + v.getBool("VERBOSE"));

  • Field Details

  • Constructor Details

    • Cli

      public Cli(String name)
      A Cli for the program name, shown in help and used for completion.

  • Method Details

    • describeRule

      public static String describeRule(String rule)
      Help text for a validation rule (spec section 5).

    • validate

      public static Object validate(String value, String rule, String name)
      Validate value against rule and return its typed form: Long for int* and port (BigInteger beyond a long), Double for float*, Boolean for bool, the String otherwise.
      Throws:
      ValidationError - with the spec's error text

    • resolvePath

      public static String resolvePath(String value, String base, List<String> searchDirs)
      Resolve a path value against base (spec section 6), trying searchDirs for bare names.

    • wrapText

      public static List<String> wrapText(String text, int width)
      Greedy word wrap that keeps existing line breaks (spec section 7).

    • setRoot

      public Cli setRoot(String root)
      Base for default path values (default: the working directory); relative to the working directory.

    • setCwd

      public Cli setCwd(String cwd)
      Base for command-line path values (default: the working directory). Resets the root to it.

    • setEnv

      public Cli setEnv(Map<String,String> env)
      The environment to read (default: the process environment).

    • setDescription

      public Cli setDescription(String text)
      Set the help description and return this CLI.

    • setEpilog

      public Cli setEpilog(String text)
      Set the final help text and return this CLI.

    • setEffects

      public Cli setEffects(String... effects)
      What running the program does: read-only, idempotent, destructive, network.

    • setStdin

      public Cli setStdin(String description, String contentType)
      What the program reads on stdin; contentType is a MIME type or a comma-separated list.

    • setStdout

      public Cli setStdout(String description, String contentType)
      What the program writes on stdout; undeclared means text.

    • exclusive

      public Cli exclusive(String... lngs)
      At most one of these options may be given.

    • requires

      public Cli requires(String lng, String... lngs)
      When lng is given, the others must be too.

    • oneOf

      public Cli oneOf(String... lngs)
      At least one of these options must be given.

    • command

      public Cli command(String word, String description)
      Register a command (spec section 1.7) and return it, to register its options and arguments on.

    • commandPath

      public List<String> commandPath()
      The command words selected by the last parse, e.g. [db, migrate].

    • setConfig

      public Cli setConfig(String option, String prefixes)
      option holds the config file path; prefixes is comma-separated.

    • requireCommand

      public Cli requireCommand(String command, String description, String installHint)
      Declare an external command the program needs.

    • setPathSearch

      public Cli setPathSearch(String lng, String dirs)
      Fallback directories (colon-separated, relative to the root) for bare relative values of a path option.

    • opt

      public Cli opt(String var, String lng, String shrt, String def, String description, String... groupAndRule)
      Register an option. def is a value, "flag", "optional", or "" (required). groupAndRule is an optional group (default "Options") and validation rule.

    • optArray

      public Cli optArray(String var, String lng, String shrt, String description, String... groupAndRule)
      Register a repeatable option whose values accumulate into a list.

    • arg

      public Cli arg(String name, String description, String def, String... rule)
      Register a positional argument. An empty def makes it required.

    • argVariadic

      public Cli argVariadic(String name, String description, String... rule)
      Register a final positional argument that collects all remaining tokens.

    • parse

      public ParseResult parse(String... argv)
      Parse without exiting. Values are in values() when the status is "ok".

    • run

      public Values run(String... argv)
      Parse like a CLI: handles --help, --help-json-schema, --completion and --bash-completion, prints errors and exits on failure. Returns the values.

    • name

      public String name()
      The program name shown in help and completion.

    • values

      public Values values()
      The resolved values from the last parse.

    • get

      public Object get(String name)
      Look up a resolved value by option variable or positional name; null when absent.

    • source

      public String source(String lng)
      Where an option's value came from: cli, config, env, default or unset.

    • isSet

      public boolean isSet(String lng)
      Whether the option came from the command line.

    • isExplicitlySet

      public boolean isExplicitlySet(String lng)
      Whether the option came from CLI, config, or environment rather than a default.

    • valuesJson

      public String valuesJson()
      Resolved values as JSON (spec section 10), in registration order.

    • usage

      public String usage()
      Help text (spec section 7), for the selected command.

    • jsonSchema

      public String jsonSchema()
      JSON description of the CLI (spec section 8).

    • completionScript

      public String completionScript(String shell)
      Shell script that enables completion for this program (spec section 9): eval "$(prog --completion bash)". Null for an unknown shell.

    • completionData

      public String completionData()
      Tab-separated completion records (spec section 9) for the program itself.

    • completionData

      public String completionData(List<String> words)
      Tab-separated completion records (spec section 9). words are the words typed after the program name; a program with commands follows them.