io.vertx.core.cli.package-info Maven / Gradle / Ivy

/*
 *  Copyright (c) 2011-2015 The original author or authors
 *  ------------------------------------------------------
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *       The Eclipse Public License is available at
 *       http://www.eclipse.org/legal/epl-v10.html
 *
 *       The Apache License v2.0 is available at
 *       http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */

/**
 * 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 {@link io.vertx.core.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 {@link io.vertx.core.cli.Option} and {@link io.vertx.core.cli.Argument} classes to
 * describe options and arguments:
 *
 * [source,$lang]
 * ----
 * {@link examples.cli.CLIExamples#example1}
 * ----
 *
 * As you can see, you can create a new {@link io.vertx.core.cli.CLI} using
 * {@link io.vertx.core.cli.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 {@code CLI} object using the
 * {@link io.vertx.core.cli.CLI#addArgument(io.vertx.core.cli.Argument)} and
 * {@link io.vertx.core.cli.CLI#addOption(io.vertx.core.cli.Option)} methods.
 *
 * ==== Options
 *
 * An {@link io.vertx.core.cli.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
 * {@link io.vertx.core.cli.Option#setFlag(boolean)}. By default, options receive a single value, however, you can
 * configure the option to receive several values using {@link io.vertx.core.cli.Option#setMultiValued(boolean)}:
 *
 * [source,$lang]
 * ----
 * {@link 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]
 * ----
 * {@link 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]
 * ----
 * {@link examples.cli.CLIExamples#example4}
 * ----
 *
 * An option can be _hidden_ using the {@link io.vertx.core.cli.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]
 * ----
 * {@link 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]
 * ----
 * {@link examples.cli.CLIExamples#example5}
 * ----
 *
 * If you don't set the argument indexes, it computes it automatically by using the declaration order.
 *
 * [source,$lang]
 * ----
 * {@link examples.cli.CLIExamples#example51}
 * ----
 *
 * The `argName` is optional and used in the usage message.
 *
 * As options, {@link io.vertx.core.cli.Argument} can:
 *
 * * be hidden using {@link io.vertx.core.cli.Argument#setHidden(boolean)}
 * * be mandatory using {@link io.vertx.core.cli.Argument#setRequired(boolean)}
 * * have a default value using {@link io.vertx.core.cli.Argument#setDefaultValue(java.lang.String)}
 * * receive several values using {@link io.vertx.core.cli.Argument#setMultiValued(boolean)} - only the last argument
 * can be multi-valued.
 *
 * Arguments can also be instantiated from their JSON form.
 *
 * ==== Usage generation
 *
 * Once your {@link io.vertx.core.cli.CLI} instance is configured, you can generate the _usage_ message:
 *
 * [source,$lang]
 * ----
 * {@link 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 {@link io.vertx.core.cli.UsageMessageFormatter} class.
 *
 * === Parsing Stage
 *
 * Once your {@link io.vertx.core.cli.CLI} instance is configured, you can parse the user command line to evaluate
 * each option and argument:
 *
 * [source,$lang]
 * ----
 * {@link examples.cli.CLIExamples#example7}
 * ----
 *
 * The {@link io.vertx.core.cli.CLI#parse(java.util.List)} method returns a {@link io.vertx.core.cli.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 {@link io.vertx.core.cli.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
 * {@link io.vertx.core.cli.CommandLine} is valid using {@link io.vertx.core.cli.CommandLine#isValid()}.
 *
 * === Query / Interrogation Stage
 *
 * Once parsed, you can retrieve the values of the options and arguments from the
 * {@link io.vertx.core.cli.CommandLine} object returned by the {@link io.vertx.core.cli.CLI#parse(java.util.List)}
 * method:
 *
 * [source,$lang]
 * ----
 * {@link 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]
 * ----
 * {@link examples.cli.CLIExamples#example9}
 * ----
 *
 * [language,java]
 * ----
 * include::cli-for-java.adoc[]
 * ----
 *
 */
@Document(fileName = "cli.adoc")
package io.vertx.core.cli;

import io.vertx.docgen.Document;