Package io.vertx.core.cli

Vert.x Core provides an API for parsing command line arguments passed to programs.

See: Description

Interface Summary

Interface	Description
CLI	Interface defining a command-line interface (in other words a command such as 'run', 'ls'...).
CommandLine	The parser transforms a CLI (a model) into an CommandLine.

Class Summary

Class	Description
Argument	Defines a command line argument.
ArgumentConverter	Converter for Argument.
Option	Models command line options.
OptionConverter	Converter for Option.
TypedArgument<T>	An implementation of Argument for java specifying the type of object received by the argument.
TypedOption<T>	An implementation of Option for java specifying the type of object received by the option.
UsageMessageFormatter	Usage message formatter.

Exception Summary

Exception	Description
AmbiguousOptionException	Exception thrown when the command line is ambiguous meaning it cannot determine exactly which option has to be set.
CLIException	High level exception thrown when an issue in the command line processing occurs.
InvalidValueException	Exception thrown when an option or an argument receives an invalid value.
MissingOptionException	Exception thrown when an option was expected and was not found on the command line.
MissingValueException	Exception thrown when an option requiring a value does not receive the value, or when a mandatory argument does not receive a value.

Package io.vertx.core.cli Description

Vert.x Core provides an API for parsing command line arguments passed to programs. It's also able to print help messages detailing the options available for a command line tool. Even if such features are far from the Vert.x core topics, this API is used in the Launcher class that you can use in _fat-jar_ and in the `vertx` command line tools. In addition, it's polyglot (can be used from any supported language) and is used in Vert.x Shell. Vert.x CLI provides a model to describe your command line interface, but also a parser. This parser supports different types of syntax: * POSIX like options (ie. `tar -zxvf foo.tar.gz`) * GNU like long options (ie. `du --human-readable --max-depth=1`) * Java like properties (ie. `java -Djava.awt.headless=true -Djava.net.useSystemProxies=true Foo`) * Short options with value attached (ie. `gcc -O2 foo.c`) * Long options with single hyphen (ie. `ant -projecthelp`) Using the CLI api is a 3-steps process: 1. The definition of the command line interface 2. The parsing of the user command line 3. The query / interrogation === Definition Stage Each command line interface must define the set of options and arguments that will be used. It also requires a name. The CLI API uses the Option and Argument classes to describe options and arguments: [source,$lang] ---- examples.cli.CLIExamples#example1 ---- As you can see, you can create a new CLI using CLI.create(java.lang.String). The passed string is the name of the CLI. Once created you can set the summary and description. The summary is intended to be short (one line), while the description can contain more details. Each option and argument are also added on the CLI object using the CLI.addArgument(io.vertx.core.cli.Argument) and CLI.addOption(io.vertx.core.cli.Option) methods. ==== Options An Option is a command line parameter identified by a _key_ present in the user command line. Options must have at least a long name or a short name. Long name are generally used using a `--` prefix, while short names are used with a single `-`. Options can get a description displayed in the usage (see below). Options can receive 0, 1 or several values. An option receiving 0 values is a `flag`, and must be declared using Option.setFlag(boolean). By default, options receive a single value, however, you can configure the option to receive several values using Option.setMultiValued(boolean): [source,$lang] ---- examples.cli.CLIExamples#example2 ---- Options can be marked as mandatory. A mandatory option not set in the user command line throws an exception during the parsing: [source,$lang] ---- examples.cli.CLIExamples#example3 ---- Non-mandatory options can have a _default value_. This value would be used if the user does not set the option in the command line: [source,$lang] ---- examples.cli.CLIExamples#example4 ---- An option can be _hidden_ using the Option.setHidden(boolean) method. Hidden option are not listed in the usage, but can still be used in the user command line (for power-users). If the option value is contrained to a fixed set, you can set the different acceptable choices: [source,$lang] ---- examples.cli.CLIExamples#example41 ---- Options can also be instantiated from their JSON form. ==== Arguments Unlike options, arguments do not have a _key_ and are identified by their _index_. For example, in `java com.acme.Foo`, `com.acme.Foo` is an argument. Arguments do not have a name, there are identified using a 0-based index. The first parameter has the index `0`: [source,$lang] ---- examples.cli.CLIExamples#example5 ---- If you don't set the argument indexes, it computes it automatically by using the declaration order. [source,$lang] ---- examples.cli.CLIExamples#example51 ---- The `argName` is optional and used in the usage message. As options, Argument can: * be hidden using Argument.setHidden(boolean) * be mandatory using Argument.setRequired(boolean) * have a default value using Argument.setDefaultValue(java.lang.String) * receive several values using Argument.setMultiValued(boolean) - only the last argument can be multi-valued. Arguments can also be instantiated from their JSON form. ==== Usage generation Once your CLI instance is configured, you can generate the _usage_ message: [source,$lang] ---- examples.cli.CLIExamples#example6 ---- It generates an usage message like this one: [source] ---- Usage: copy [-R] source target A command line interface to copy files. -R,--directory enables directory support ---- If you need to tune the usage message, check the UsageMessageFormatter class. === Parsing Stage Once your CLI instance is configured, you can parse the user command line to evaluate each option and argument: [source,$lang] ---- examples.cli.CLIExamples#example7 ---- The CLI.parse(java.util.List) method returns a CommandLine object containing the values. By default, it validates the user command line and checks that each mandatory options and arguments have been set as well as the number of values received by each option. You can disable the validation by passing `false` as second parameter of CLI.parse(java.util.List, boolean). This is useful if you want to check an argument or option is present even if the parsed command line is invalid. You can check whether or not the CommandLine is valid using CommandLine.isValid(). === Query / Interrogation Stage Once parsed, you can retrieve the values of the options and arguments from the CommandLine object returned by the CLI.parse(java.util.List) method: [source,$lang] ---- examples.cli.CLIExamples#example8 ---- One of your option can have been marked as "help". If a user command line enabled a "help" option, the validation won't failed, but give you the opportunity to check if the user asks for help: [source,$lang] ---- examples.cli.CLIExamples#example9 ---- [language,java] ---- include::cli-for-java.adoc[] ----