io.vertx.core.cli

Interface CLI

public interface CLI

Interface defining a command-line interface (in other words a command such as 'run', 'ls'...). This interface is polyglot to ease reuse such as in Vert.x Shell.

A command line interface has a name, and defines a set of options and arguments. Options are key-value pair such as -foo=bar or -flag. The supported formats depend on the used parser. Arguments are unlike options raw values. Options are defined using Option, while argument are defined using Argument.

Command line interfaces also define a summary and a description. These attributes are used in the usage generation . To disable the help generation, set the hidden attribute to true.

Command Line Interface object does not contains "value", it's a model. It must be evaluated by a parser that returns a CommandLine object containing the argument and option values.

Author:

Clement Escoffier

See Also:

Argument, Option

Method Summary

Modifier and Type	Method and Description
CLI	addArgument(Argument arg) Adds an argument.
CLI	addArguments(List<Argument> args) Adds a set of arguments.
CLI	addOption(Option option) Adds an option.
CLI	addOptions(List<Option> options) Adds a set of options.
static CLI	create(Class<?> clazz) Creates an instance of CLI from the given Java class.
static CLI	create(String name) Creates an instance of CLI using the default implementation.
Argument	getArgument(int index) Gets an Argument based on its index.
Argument	getArgument(String name) Gets an Argument based on its name (argument name).
List<Argument>	getArguments() Gets the list of defined arguments.
String	getDescription()
String	getName()
Option	getOption(String name) Gets an Option based on its name (short name, long name or argument name).
List<Option>	getOptions() Gets the list of options.
int	getPriority()
String	getSummary()
boolean	isHidden() Checks whether or not the current CLI instance is hidden.
CommandLine	parse(List<String> arguments) Parses the user command line interface and create a new CommandLine containing extracting values.
CommandLine	parse(List<String> arguments, boolean validate) Parses the user command line interface and create a new CommandLine containing extracting values.
CLI	removeArgument(int index) Removes an argument identified by its index.
CLI	removeOption(String name) Removes an option identified by its name.
CLI	setArguments(List<Argument> args) Sets the list of arguments.
CLI	setDescription(String desc)
CLI	setHidden(boolean hidden) Sets whether or not the current instance of CLI must be hidden.
CLI	setName(String name) Sets the name of the CLI.
CLI	setOptions(List<Option> options) Sets the list of arguments.
CLI	setPriority(int priority) Sets the priority of the CLI.
CLI	setSummary(String summary) Sets the summary of the CLI.
CLI	usage(StringBuilder builder) Generates the usage / help of the current CLI.
CLI	usage(StringBuilder builder, String prefix) Generates the usage / help of the current CLI.

Method Detail

create

static CLI create(String name)

Creates an instance of CLI using the default implementation.

Parameters:

name - the name of the CLI (must not be null)

Returns:

the created instance of CLI

create

static CLI create(Class<?> clazz)

Creates an instance of CLI from the given Java class. It instantiates the CLI object from the annotations used in the class.

Parameters:

clazz - the annotated class

Returns:

the created instance of CLI

parse

CommandLine parse(List<String> arguments)

Parses the user command line interface and create a new CommandLine containing extracting values.

Parameters:

arguments - the arguments

Returns:

the creates command line

parse

CommandLine parse(List<String> arguments,
                  boolean validate)

Parses the user command line interface and create a new CommandLine containing extracting values.

Parameters:

arguments - the arguments

validate - enable / disable parsing validation

Returns:

the creates command line

getName

String getName()

Returns:

the CLI name.

setName

CLI setName(String name)

Sets the name of the CLI.

Parameters:

name - the name

Returns:

the current CLI instance

getDescription

String getDescription()

Returns:

the CLI description.

setDescription

CLI setDescription(String desc)

getSummary

String getSummary()

Returns:

the CLI summary.

setSummary

CLI setSummary(String summary)

Sets the summary of the CLI.

Parameters:

summary - the summary

Returns:

the current CLI instance

isHidden

boolean isHidden()

Checks whether or not the current CLI instance is hidden.

Returns:

true if the current CLI is hidden, false otherwise

setHidden

CLI setHidden(boolean hidden)

Sets whether or not the current instance of CLI must be hidden. Hidden CLI are not listed when displaying usages / help messages. In other words, hidden commands are for power user.

Parameters:

hidden - enables or disables the hidden aspect of the CI

Returns:

the current CLI instance

getOptions

List<Option> getOptions()

Gets the list of options.

Returns:

the list of options, empty if none.

addOption

CLI addOption(Option option)

Adds an option.

Parameters:

option - the option, must not be null.

Returns:

the current CLI instance

addOptions

CLI addOptions(List<Option> options)

Adds a set of options. Unlike setOptions(List)}, this method does not remove the existing options. The given list is appended to the existing list.

Parameters:

options - the options, must not be null

Returns:

the current CLI instance

setOptions

CLI setOptions(List<Option> options)

Sets the list of arguments.

Parameters:

options - the list of options, must not be null

Returns:

the current CLI instance

getArguments

List<Argument> getArguments()

Gets the list of defined arguments.

Returns:

the list of argument, empty if none.

addArgument

CLI addArgument(Argument arg)

Adds an argument.

Parameters:

arg - the argument, must not be null

Returns:

the current CLI instance

addArguments

CLI addArguments(List<Argument> args)

Adds a set of arguments. Unlike setArguments(List), this method does not remove the existing arguments. The given list is appended to the existing list.

Parameters:

args - the arguments, must not be null

Returns:

the current CLI instance

setArguments

CLI setArguments(List<Argument> args)

Sets the list of arguments.

Parameters:

args - the list of arguments, must not be null

Returns:

the current CLI instance

getOption

Option getOption(String name)

Gets an Option based on its name (short name, long name or argument name).

Parameters:

name - the name, must not be null

Returns:

the Option, null if not found

getArgument

Argument getArgument(String name)

Gets an Argument based on its name (argument name).

Parameters:

name - the name of the argument, must not be null

Returns:

the Argument, null if not found.

getArgument

Argument getArgument(int index)

Gets an Argument based on its index.

Parameters:

index - the index, must be positive or zero.

Returns:

the Argument, null if not found.

removeOption

CLI removeOption(String name)

Removes an option identified by its name. This method does nothing if the option cannot be found.

Parameters:

name - the option name

Returns:

the current CLI instance

removeArgument

CLI removeArgument(int index)

Removes an argument identified by its index. This method does nothing if the argument cannot be found.

Parameters:

index - the argument index

Returns:

the current CLI instance

usage

CLI usage(StringBuilder builder)

Generates the usage / help of the current CLI.

Parameters:

builder - the string builder in which the help is going to be printed

Returns:

the current CLI instance

usage

CLI usage(StringBuilder builder,
          String prefix)

Generates the usage / help of the current CLI.

Parameters:

builder - the string builder in which the help is going to be printed

prefix - an optional prefix

Returns:

the current CLI instance

getPriority

int getPriority()

Returns:

the CLI priority.

setPriority

CLI setPriority(int priority)

Sets the priority of the CLI.

Parameters:

priority - the priority

Returns:

the current CLI instance