• Home
• io.vertx
• vertx-core
• 4.5.9
• source code
• CLI.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

io.vertx.core.cli.CLI Maven / Gradle / Ivy

/*
 * Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.cli;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.Nullable;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.cli.annotations.CLIConfigurator;
import io.vertx.core.cli.impl.DefaultCLI;

import java.util.List;

/**
 * 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 {@code -foo=bar} or {@code -flag}. The supported formats depend on the used parser. Arguments are unlike
 * options raw values. Options are defined using
 * {@link Option}, while argument are defined using {@link 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 {@code hidden} attribute to {@code true}.
 * 

 * Command Line Interface object does not contains "value", it's a model. It must be evaluated by a
 * parser that returns a {@link CommandLine} object containing the argument and option values.
 *
 * @author Clement Escoffier 
 * @see Argument
 * @see Option
 */
@VertxGen
public interface CLI {

  /**
   * Creates an instance of {@link CLI} using the default implementation.
   *
   * @param name the name of the CLI (must not be {@code null})
   * @return the created instance of {@link CLI}
   */
  static CLI create(String name) {
    return new DefaultCLI().setName(name);
  }

  /**
   * Creates an instance of {@link CLI} from the given Java class. It instantiates the {@link CLI} object from the
   * annotations used in the class.
   *
   * @param clazz the annotated class
   * @return the created instance of {@link CLI}
   */
  @GenIgnore
  static CLI create(Class clazz) {
    return CLIConfigurator.define(clazz);
  }

  /**
   * Parses the user command line interface and create a new {@link CommandLine} containing extracting values.
   *
   * @param arguments the arguments
   * @return the creates command line
   */
  CommandLine parse(List arguments);

  /**
   * Parses the user command line interface and create a new {@link CommandLine} containing extracting values.
   *
   * @param arguments the arguments
   * @param validate  enable / disable parsing validation
   * @return the creates command line
   */
  CommandLine parse(List arguments, boolean validate);

  /**
   * @return the CLI name.
   */
  String getName();

  /**
   * Sets the name of the CLI.
   *
   * @param name the name
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI setName(String name);

  /**
   * @return the CLI description.
   */
  @Nullable String getDescription();

  @Fluent
  CLI setDescription(String desc);

  /**
   * @return the CLI summary.
   */
  @Nullable String getSummary();

  /**
   * Sets the summary of the CLI.
   *
   * @param summary the summary
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI setSummary(String summary);

  /**
   * Checks whether or not the current {@link CLI} instance is hidden.
   *
   * @return {@code true} if the current {@link CLI} is hidden, {@link false} otherwise
   */
  boolean isHidden();

  /**
   * Sets whether or not the current instance of {@link CLI} must be hidden. Hidden CLI are not listed when
   * displaying usages / help messages. In other words, hidden commands are for power user.
   *
   * @param hidden enables or disables the hidden aspect of the CI
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI setHidden(boolean hidden);

  /**
   * Gets the list of options.
   *
   * @return the list of options, empty if none.
   */
  List getOptions();

  /**
   * Adds an option.
   *
   * @param option the option, must not be {@code null}.
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI addOption(Option option);

  /**
   * Adds a set of options. Unlike {@link #setOptions(List)}}, this method does not remove the existing options.
   * The given list is appended to the existing list.
   *
   * @param options the options, must not be {@code null}
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI addOptions(List options);

  /**
   * Sets the list of arguments.
   *
   * @param options the list of options, must not be {@code null}
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI setOptions(List options);

  /**
   * Gets the list of defined arguments.
   *
   * @return the list of argument, empty if none.
   */
  List getArguments();

  /**
   * Adds an argument.
   *
   * @param arg the argument, must not be {@code null}
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI addArgument(Argument arg);

  /**
   * Adds a set of arguments. Unlike {@link #setArguments(List)}, this method does not remove the existing arguments.
   * The given list is appended to the existing list.
   *
   * @param args the arguments, must not be {@code null}
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI addArguments(List args);

  /**
   * Sets the list of arguments.
   *
   * @param args the list of arguments, must not be {@code null}
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI setArguments(List args);

  /**
   * Gets an {@link Option} based on its name (short name, long name or argument name).
   *
   * @param name the name, must not be {@code null}
   * @return the {@link Option}, {@code null} if not found
   */
  @Nullable
  Option getOption(String name);

  /**
   * Gets an {@link Argument} based on its name (argument name).
   *
   * @param name the name of the argument, must not be {@code null}
   * @return the {@link Argument}, {@code null} if not found.
   */
  @Nullable
  Argument getArgument(String name);

  /**
   * Gets an {@link Argument} based on its index.
   *
   * @param index the index, must be positive or zero.
   * @return the {@link Argument}, {@code null} if not found.
   */
  @Nullable
  Argument getArgument(int index);

  /**
   * Removes an option identified by its name. This method does nothing if the option cannot be found.
   *
   * @param name the option name
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI removeOption(String name);

  /**
   * Removes an argument identified by its index. This method does nothing if the argument cannot be found.
   *
   * @param index the argument index
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI removeArgument(int index);

  /**
   * Generates the usage / help of the current {@link CLI}.
   *
   * @param builder the string builder in which the help is going to be printed
   * @return the current {@link CLI} instance
   */
  @GenIgnore
  CLI usage(StringBuilder builder);

  /**
   * Generates the usage / help of the current {@link CLI}.
   *
   * @param builder the string builder in which the help is going to be printed
   * @param prefix  an optional prefix
   * @return the current {@link CLI} instance
   */
  @GenIgnore
  CLI usage(StringBuilder builder, String prefix);

  /**
   * @return the CLI priority.
   */
  int getPriority();

  /**
   * Sets the priority of the CLI.
   *
   * @param priority the priority
   * @return the current {@link CLI} instance
   */
  @Fluent
  CLI setPriority(int priority);
}