You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rp...@apache.org on 2017/08/15 22:23:51 UTC
[07/10] logging-log4j2 git commit: LOG4J2-2011 moved classes from
util.picocli to tools.picocli
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/e2f9d5ed/log4j-core/src/main/java/org/apache/logging/log4j/core/util/picocli/CommandLine.java
----------------------------------------------------------------------
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/util/picocli/CommandLine.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/util/picocli/CommandLine.java
deleted file mode 100644
index 5c4e9cc..0000000
--- a/log4j-core/src/main/java/org/apache/logging/log4j/core/util/picocli/CommandLine.java
+++ /dev/null
@@ -1,3900 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache license, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the license for the specific language governing permissions and
- * limitations under the license.
- */
-package org.apache.logging.log4j.core.util.picocli;
-
-import java.awt.Point;
-import java.io.File;
-import java.io.PrintStream;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-import java.lang.reflect.Array;
-import java.lang.reflect.Constructor;
-import java.lang.reflect.Field;
-import java.math.BigDecimal;
-import java.math.BigInteger;
-import java.net.InetAddress;
-import java.net.MalformedURLException;
-import java.net.URI;
-import java.net.URISyntaxException;
-import java.net.URL;
-import java.nio.charset.Charset;
-import java.nio.file.Path;
-import java.nio.file.Paths;
-import java.sql.Time;
-import java.text.BreakIterator;
-import java.text.ParseException;
-import java.text.SimpleDateFormat;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.Collections;
-import java.util.Comparator;
-import java.util.Date;
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.LinkedHashMap;
-import java.util.LinkedList;
-import java.util.List;
-import java.util.Map;
-import java.util.Queue;
-import java.util.Set;
-import java.util.SortedMap;
-import java.util.SortedSet;
-import java.util.Stack;
-import java.util.TreeMap;
-import java.util.TreeSet;
-import java.util.UUID;
-import java.util.regex.Pattern;
-
-import org.apache.logging.log4j.core.util.picocli.CommandLine.Help.Ansi;
-import org.apache.logging.log4j.core.util.picocli.CommandLine.Help.Ansi.IStyle;
-import org.apache.logging.log4j.core.util.picocli.CommandLine.Help.Ansi.Style;
-import org.apache.logging.log4j.core.util.picocli.CommandLine.Help.Ansi.Text;
-
-import static java.util.Locale.ENGLISH;
-import static org.apache.logging.log4j.core.util.picocli.CommandLine.Help.Column.Overflow.SPAN;
-import static org.apache.logging.log4j.core.util.picocli.CommandLine.Help.Column.Overflow.TRUNCATE;
-import static org.apache.logging.log4j.core.util.picocli.CommandLine.Help.Column.Overflow.WRAP;
-
-/**
- * <p>
- * CommandLine interpreter that uses reflection to initialize an annotated domain object with values obtained from the
- * command line arguments.
- * </p><h2>Example</h2>
- * <pre>import static picocli.CommandLine.*;
- *
- * @Command(header = "Encrypt FILE(s), or standard input, to standard output or to the output file.")
- * public class Encrypt {
- *
- * @Parameters(type = File.class, description = "Any number of input files")
- * private List<File> files = new ArrayList<File>();
- *
- * @Option(names = { "-o", "--out" }, description = "Output file (default: print to console)")
- * private File outputFile;
- *
- * @Option(names = { "-v", "--verbose"}, description = "Verbosely list files processed")
- * private boolean verbose;
- *
- * @Option(names = { "-h", "--help", "-?", "-help"}, help = true, description = "Display this help and exit")
- * private boolean help;
- * }
- * </pre>
- * <p>
- * Use {@code CommandLine} to initialize a domain object as follows:
- * </p><pre>
- * public static void main(String... args) {
- * try {
- * Encrypt encrypt = CommandLine.populateCommand(new Encrypt(), args);
- * if (encrypt.help) {
- * CommandLine.usage(encrypt, System.out);
- * } else {
- * runProgram(encrypt);
- * }
- * } catch (ParameterException ex) { // command line arguments could not be parsed
- * System.err.println(ex.getMessage());
- * CommandLine.usage(new Encrypt(), System.err);
- * }
- * }
- * </pre><p>
- * Invoke the above program with some command line arguments. The below are all equivalent:
- * </p>
- * <pre>
- * --verbose --out=outfile in1 in2
- * --verbose --out outfile in1 in2
- * -v --out=outfile in1 in2
- * -v -o outfile in1 in2
- * -v -o=outfile in1 in2
- * -vo outfile in1 in2
- * -vo=outfile in1 in2
- * -v -ooutfile in1 in2
- * -vooutfile in1 in2
- * </pre>
- *
- * <p>
- * Copied and modified from <a href="http://github.com/remkop/picocli/">picocli</a>.
- * </p>
- *
- * @since 2.9
- */
-public class CommandLine {
- /** This is picocli version {@value}. */
- public static final String VERSION = "0.9.8";
-
- private final Interpreter interpreter;
- private boolean overwrittenOptionsAllowed = false;
- private boolean unmatchedArgumentsAllowed = false;
- private List<String> unmatchedArguments = new ArrayList<String>();
- private CommandLine parent;
- private boolean usageHelpRequested;
- private boolean versionHelpRequested;
- private List<String> versionLines = new ArrayList<String>();
-
- /**
- * Constructs a new {@code CommandLine} interpreter with the specified annotated object.
- * When the {@link #parse(String...)} method is called, fields of the specified object that are annotated
- * with {@code @Option} or {@code @Parameters} will be initialized based on command line arguments.
- * @param command the object to initialize from the command line arguments
- * @throws IllegalArgumentException if the specified command object does not have a {@link Command}, {@link Option} or {@link Parameters} annotation
- */
- public CommandLine(Object command) {
- interpreter = new Interpreter(command);
- }
-
- /** Registers a subcommand with the specified name. For example:
- * <pre>
- * CommandLine commandLine = new CommandLine(new Git())
- * .addSubcommand("status", new GitStatus())
- * .addSubcommand("commit", new GitCommit();
- * .addSubcommand("add", new GitAdd())
- * .addSubcommand("branch", new GitBranch())
- * .addSubcommand("checkout", new GitCheckout())
- * //...
- * ;
- * </pre>
- *
- * <p>The specified object can be an annotated object or a
- * {@code CommandLine} instance with its own nested subcommands. For example:</p>
- * <pre>
- * CommandLine commandLine = new CommandLine(new MainCommand())
- * .addSubcommand("cmd1", new ChildCommand1()) // subcommand
- * .addSubcommand("cmd2", new ChildCommand2())
- * .addSubcommand("cmd3", new CommandLine(new ChildCommand3()) // subcommand with nested sub-subcommands
- * .addSubcommand("cmd3sub1", new GrandChild3Command1())
- * .addSubcommand("cmd3sub2", new GrandChild3Command2())
- * .addSubcommand("cmd3sub3", new CommandLine(new GrandChild3Command3()) // deeper nesting
- * .addSubcommand("cmd3sub3sub1", new GreatGrandChild3Command3_1())
- * .addSubcommand("cmd3sub3sub2", new GreatGrandChild3Command3_2())
- * )
- * );
- * </pre>
- * <p>The default type converters are available on all subcommands and nested sub-subcommands, but custom type
- * converters are registered only with the subcommand hierarchy as it existed when the custom type was registered.
- * To ensure a custom type converter is available to all subcommands, register the type converter last, after
- * adding subcommands.</p>
- *
- * @param name the string to recognize on the command line as a subcommand
- * @param command the object to initialize with command line arguments following the subcommand name.
- * This may be a {@code CommandLine} instance with its own (nested) subcommands
- * @return this CommandLine object, to allow method chaining
- * @see #registerConverter(Class, ITypeConverter)
- * @since 0.9.7
- */
- public CommandLine addSubcommand(String name, Object command) {
- CommandLine commandLine = toCommandLine(command);
- commandLine.parent = this;
- interpreter.commands.put(name, commandLine);
- return this;
- }
- /** Returns a map with the subcommands {@linkplain #addSubcommand(String, Object) registered} on this instance.
- * @return a map with the registered subcommands
- * @since 0.9.7
- */
- public Map<String, CommandLine> getSubcommands() {
- return new LinkedHashMap<String, CommandLine>(interpreter.commands);
- }
- /**
- * Returns the command that this is a subcommand of, or {@code null} if this is a top-level command.
- * @return the command that this is a subcommand of, or {@code null} if this is a top-level command
- * @see #addSubcommand(String, Object)
- * @see Command#subcommands()
- * @since 0.9.8
- */
- public CommandLine getParent() {
- return parent;
- }
-
- /**
- * Returns the annotated object that this {@code CommandLine} instance was constructed with.
- * @return the annotated object that this {@code CommandLine} instance was constructed with
- * @since 0.9.7
- */
- public Object getCommand() {
- return interpreter.command;
- }
-
- /** Returns {@code true} if an option annotated with {@link Option#usageHelp()} was specified on the command line.
- * @return whether the parser encountered an option annotated with {@link Option#usageHelp()} */
- public boolean isUsageHelpRequested() { return usageHelpRequested; }
-
- /** Returns {@code true} if an option annotated with {@link Option#versionHelp()} was specified on the command line.
- * @return whether the parser encountered an option annotated with {@link Option#versionHelp()} */
- public boolean isVersionHelpRequested() { return versionHelpRequested; }
-
- /** Returns whether options for single-value fields can be specified multiple times on the command line.
- * The default is {@code false} and a {@link OverwrittenOptionException} is thrown if this happens.
- * When {@code true}, the last specified value is retained.
- * @return {@code true} if options for single-value fields can be specified multiple times on the command line, {@code false} otherwise
- * @since 0.9.7
- */
- public boolean isOverwrittenOptionsAllowed() {
- return overwrittenOptionsAllowed;
- }
-
- /** Sets whether options for single-value fields can be specified multiple times on the command line without a {@link OverwrittenOptionException} being thrown.
- * <p>The specified setting will be registered with this {@code CommandLine} and the full hierarchy of its
- * subcommands and nested sub-subcommands <em>at the moment this method is called</em>. Subcommands added
- * later will have the default setting. To ensure a setting is applied to all
- * subcommands, call the setter last, after adding subcommands.</p>
- * @param newValue the new setting
- * @return this {@code CommandLine} object, to allow method chaining
- * @since 0.9.7
- */
- public CommandLine setOverwrittenOptionsAllowed(boolean newValue) {
- this.overwrittenOptionsAllowed = newValue;
- for (CommandLine command : interpreter.commands.values()) {
- command.setOverwrittenOptionsAllowed(newValue);
- }
- return this;
- }
-
- /** Returns whether the end user may specify arguments on the command line that are not matched to any option or parameter fields.
- * The default is {@code false} and a {@link UnmatchedArgumentException} is thrown if this happens.
- * When {@code true}, the last unmatched arguments are available via the {@link #getUnmatchedArguments()} method.
- * @return {@code true} if the end use may specify unmatched arguments on the command line, {@code false} otherwise
- * @see #getUnmatchedArguments()
- * @since 0.9.7
- */
- public boolean isUnmatchedArgumentsAllowed() {
- return unmatchedArgumentsAllowed;
- }
-
- /** Sets whether the end user may specify unmatched arguments on the command line without a {@link UnmatchedArgumentException} being thrown.
- * <p>The specified setting will be registered with this {@code CommandLine} and the full hierarchy of its
- * subcommands and nested sub-subcommands <em>at the moment this method is called</em>. Subcommands added
- * later will have the default setting. To ensure a setting is applied to all
- * subcommands, call the setter last, after adding subcommands.</p>
- * @param newValue the new setting
- * @return this {@code CommandLine} object, to allow method chaining
- * @since 0.9.7
- */
- public CommandLine setUnmatchedArgumentsAllowed(boolean newValue) {
- this.unmatchedArgumentsAllowed = newValue;
- for (CommandLine command : interpreter.commands.values()) {
- command.setUnmatchedArgumentsAllowed(newValue);
- }
- return this;
- }
-
- /** Returns the list of unmatched command line arguments, if any.
- * @return the list of unmatched command line arguments or an empty list
- * @see #isUnmatchedArgumentsAllowed()
- * @since 0.9.7
- */
- public List<String> getUnmatchedArguments() {
- return unmatchedArguments;
- }
-
- /**
- * <p>
- * Convenience method that initializes the specified annotated object from the specified command line arguments.
- * </p><p>
- * This is equivalent to
- * </p><pre>
- * CommandLine cli = new CommandLine(command);
- * cli.parse(args);
- * return command;
- * </pre>
- *
- * @param command the object to initialize. This object contains fields annotated with
- * {@code @Option} or {@code @Parameters}.
- * @param args the command line arguments to parse
- * @param <T> the type of the annotated object
- * @return the specified annotated object
- * @throws IllegalArgumentException if the specified command object does not have a {@link Command}, {@link Option} or {@link Parameters} annotation
- * @throws ParameterException if the specified command line arguments are invalid
- * @since 0.9.7
- */
- public static <T> T populateCommand(T command, String... args) {
- CommandLine cli = toCommandLine(command);
- cli.parse(args);
- return command;
- }
-
- /**
- * <p>
- * Initializes the annotated object that this {@code CommandLine} was constructed with as well as
- * possibly any registered commands, based on the specified command line arguments,
- * and returns a list of all commands and subcommands that were initialized by this method.
- * </p>
- *
- * @param args the command line arguments to parse
- * @return a list with all commands and subcommands initialized by this method
- * @throws ParameterException if the specified command line arguments are invalid
- */
- public List<CommandLine> parse(String... args) {
- return interpreter.parse(args);
- }
-
- /**
- * Equivalent to {@code new CommandLine(command).usage(out)}. See {@link #usage(PrintStream)} for details.
- * @param command the object annotated with {@link Command}, {@link Option} and {@link Parameters}
- * @param out the print stream to print the help message to
- * @throws IllegalArgumentException if the specified command object does not have a {@link Command}, {@link Option} or {@link Parameters} annotation
- */
- public static void usage(Object command, PrintStream out) {
- toCommandLine(command).usage(out);
- }
-
- /**
- * Equivalent to {@code new CommandLine(command).usage(out, ansi)}.
- * See {@link #usage(PrintStream, Help.Ansi)} for details.
- * @param command the object annotated with {@link Command}, {@link Option} and {@link Parameters}
- * @param out the print stream to print the help message to
- * @param ansi whether the usage message should contain ANSI escape codes or not
- * @throws IllegalArgumentException if the specified command object does not have a {@link Command}, {@link Option} or {@link Parameters} annotation
- */
- public static void usage(Object command, PrintStream out, Help.Ansi ansi) {
- toCommandLine(command).usage(out, ansi);
- }
-
- /**
- * Equivalent to {@code new CommandLine(command).usage(out, colorScheme)}.
- * See {@link #usage(PrintStream, Help.ColorScheme)} for details.
- * @param command the object annotated with {@link Command}, {@link Option} and {@link Parameters}
- * @param out the print stream to print the help message to
- * @param colorScheme the {@code ColorScheme} defining the styles for options, parameters and commands when ANSI is enabled
- * @throws IllegalArgumentException if the specified command object does not have a {@link Command}, {@link Option} or {@link Parameters} annotation
- */
- public static void usage(Object command, PrintStream out, Help.ColorScheme colorScheme) {
- toCommandLine(command).usage(out, colorScheme);
- }
-
- /**
- * Delegates to {@link #usage(PrintStream, Help.Ansi)} with the {@linkplain Help.Ansi#AUTO platform default}.
- * @param out the printStream to print to
- * @see #usage(PrintStream, Help.ColorScheme)
- */
- public void usage(PrintStream out) {
- usage(out, Help.Ansi.AUTO);
- }
-
- /**
- * Delegates to {@link #usage(PrintStream, Help.ColorScheme)} with the {@linkplain Help#defaultColorScheme(CommandLine.Help.Ansi) default color scheme}.
- * @param out the printStream to print to
- * @param ansi whether the usage message should include ANSI escape codes or not
- * @see #usage(PrintStream, Help.ColorScheme)
- */
- public void usage(PrintStream out, Help.Ansi ansi) {
- usage(out, Help.defaultColorScheme(ansi));
- }
- /**
- * Prints a usage help message for the annotated command class to the specified {@code PrintStream}.
- * Delegates construction of the usage help message to the {@link Help} inner class and is equivalent to:
- * <pre>
- * Help help = new Help(command).addAllSubcommands(getSubcommands());
- * StringBuilder sb = new StringBuilder()
- * .append(help.headerHeading())
- * .append(help.header())
- * .append(help.synopsisHeading()) //e.g. Usage:
- * .append(help.synopsis()) //e.g. <main class> [OPTIONS] <command> [COMMAND-OPTIONS] [ARGUMENTS]
- * .append(help.descriptionHeading()) //e.g. %nDescription:%n%n
- * .append(help.description()) //e.g. {"Converts foos to bars.", "Use options to control conversion mode."}
- * .append(help.parameterListHeading()) //e.g. %nPositional parameters:%n%n
- * .append(help.parameterList()) //e.g. [FILE...] the files to convert
- * .append(help.optionListHeading()) //e.g. %nOptions:%n%n
- * .append(help.optionList()) //e.g. -h, --help displays this help and exits
- * .append(help.commandListHeading()) //e.g. %nCommands:%n%n
- * .append(help.commandList()) //e.g. add adds the frup to the frooble
- * .append(help.footerHeading())
- * .append(help.footer());
- * out.print(sb);
- * </pre>
- * <p>Annotate your class with {@link Command} to control many aspects of the usage help message, including
- * the program name, text of section headings and section contents, and some aspects of the auto-generated sections
- * of the usage help message.
- * <p>To customize the auto-generated sections of the usage help message, like how option details are displayed,
- * instantiate a {@link Help} object and use a {@link Help.TextTable} with more of fewer columns, a custom
- * {@linkplain Help.Layout layout}, and/or a custom option {@linkplain Help.IOptionRenderer renderer}
- * for ultimate control over which aspects of an Option or Field are displayed where.</p>
- * @param out the {@code PrintStream} to print the usage help message to
- * @param colorScheme the {@code ColorScheme} defining the styles for options, parameters and commands when ANSI is enabled
- */
- public void usage(PrintStream out, Help.ColorScheme colorScheme) {
- Help help = new Help(interpreter.command, colorScheme).addAllSubcommands(getSubcommands());
- StringBuilder sb = new StringBuilder()
- .append(help.headerHeading())
- .append(help.header())
- .append(help.synopsisHeading()) //e.g. Usage:
- .append(help.synopsis(help.synopsisHeadingLength())) //e.g. <main class> [OPTIONS] <command> [COMMAND-OPTIONS] [ARGUMENTS]
- .append(help.descriptionHeading()) //e.g. %nDescription:%n%n
- .append(help.description()) //e.g. {"Converts foos to bars.", "Use options to control conversion mode."}
- .append(help.parameterListHeading()) //e.g. %nPositional parameters:%n%n
- .append(help.parameterList()) //e.g. [FILE...] the files to convert
- .append(help.optionListHeading()) //e.g. %nOptions:%n%n
- .append(help.optionList()) //e.g. -h, --help displays this help and exits
- .append(help.commandListHeading()) //e.g. %nCommands:%n%n
- .append(help.commandList()) //e.g. add adds the frup to the frooble
- .append(help.footerHeading())
- .append(help.footer());
- out.print(sb);
- }
-
- /**
- * Delegates to {@link #printVersionHelp(PrintStream, Help.Ansi)} with the {@linkplain Help.Ansi#AUTO platform default}.
- * @param out the printStream to print to
- * @see #printVersionHelp(PrintStream, Help.Ansi)
- */
- public void printVersionHelp(PrintStream out) { printVersionHelp(out, Help.Ansi.AUTO); }
-
- /**
- * Prints version information from the {@link Command#version()} annotation to the specified {@code PrintStream}.
- * Each element of the array of version strings is printed on a separate line. Version strings may contain
- * <a href="http://picocli.info/#_usage_help_with_styles_and_colors">markup for colors and style</a>.
- * @param out the printStream to print to
- * @param ansi whether the usage message should include ANSI escape codes or not
- * @see Command#version()
- * @see Option#versionHelp()
- * @see #isVersionHelpRequested()
- */
- public void printVersionHelp(PrintStream out, Help.Ansi ansi) {
- for (String versionInfo : versionLines) {
- out.println(ansi.new Text(versionInfo));
- }
- }
-
- /**
- * Delegates to {@link #run(Runnable, PrintStream, Help.Ansi, String...)} with {@link Help.Ansi#AUTO}.
- * @param command the command to run when {@linkplain #populateCommand(Object, String...) parsing} succeeds.
- * @param out the printStream to print to
- * @param args the command line arguments to parse
- * @param <R> the annotated object must implement Runnable
- * @see #run(Runnable, PrintStream, Help.Ansi, String...)
- * @throws IllegalArgumentException if the specified command object does not have a {@link Command}, {@link Option} or {@link Parameters} annotation
- */
- public static <R extends Runnable> void run(R command, PrintStream out, String... args) {
- run(command, out, Help.Ansi.AUTO, args);
- }
- /**
- * Convenience method to allow command line application authors to avoid some boilerplate code in their application.
- * The annotated object needs to implement {@link Runnable}. Calling this method is equivalent to:
- * <pre>
- * CommandLine cmd = new CommandLine(command);
- * try {
- * cmd.parse(args);
- * } catch (Exception ex) {
- * System.err.println(ex.getMessage());
- * cmd.usage(out, ansi);
- * return;
- * }
- * command.run();
- * </pre>
- * Note that this method is not suitable for commands with subcommands.
- * @param command the command to run when {@linkplain #populateCommand(Object, String...) parsing} succeeds.
- * @param out the printStream to print to
- * @param ansi whether the usage message should include ANSI escape codes or not
- * @param args the command line arguments to parse
- * @param <R> the annotated object must implement Runnable
- * @throws IllegalArgumentException if the specified command object does not have a {@link Command}, {@link Option} or {@link Parameters} annotation
- */
- public static <R extends Runnable> void run(R command, PrintStream out, Help.Ansi ansi, String... args) {
- CommandLine cmd = new CommandLine(command); // validate command outside of try-catch
- try {
- cmd.parse(args);
- } catch (Exception ex) {
- out.println(ex.getMessage());
- cmd.usage(out, ansi);
- return;
- }
- command.run();
- }
-
- /**
- * Registers the specified type converter for the specified class. When initializing fields annotated with
- * {@link Option}, the field's type is used as a lookup key to find the associated type converter, and this
- * type converter converts the original command line argument string value to the correct type.
- * <p>
- * Java 8 lambdas make it easy to register custom type converters:
- * </p>
- * <pre>
- * commandLine.registerConverter(java.nio.file.Path.class, s -> java.nio.file.Paths.get(s));
- * commandLine.registerConverter(java.time.Duration.class, s -> java.time.Duration.parse(s));</pre>
- * <p>
- * Built-in type converters are pre-registered for the following java 1.5 types:
- * </p>
- * <ul>
- * <li>all primitive types</li>
- * <li>all primitive wrapper types: Boolean, Byte, Character, Double, Float, Integer, Long, Short</li>
- * <li>any enum</li>
- * <li>java.io.File</li>
- * <li>java.math.BigDecimal</li>
- * <li>java.math.BigInteger</li>
- * <li>java.net.InetAddress</li>
- * <li>java.net.URI</li>
- * <li>java.net.URL</li>
- * <li>java.nio.charset.Charset</li>
- * <li>java.sql.Time</li>
- * <li>java.util.Date</li>
- * <li>java.util.UUID</li>
- * <li>java.util.regex.Pattern</li>
- * <li>StringBuilder</li>
- * <li>CharSequence</li>
- * <li>String</li>
- * </ul>
- * <p>The specified converter will be registered with this {@code CommandLine} and the full hierarchy of its
- * subcommands and nested sub-subcommands <em>at the moment the converter is registered</em>. Subcommands added
- * later will not have this converter added automatically. To ensure a custom type converter is available to all
- * subcommands, register the type converter last, after adding subcommands.</p>
- *
- * @param cls the target class to convert parameter string values to
- * @param converter the class capable of converting string values to the specified target type
- * @param <K> the target type
- * @return this CommandLine object, to allow method chaining
- * @see #addSubcommand(String, Object)
- */
- public <K> CommandLine registerConverter(Class<K> cls, ITypeConverter<K> converter) {
- interpreter.converterRegistry.put(Assert.notNull(cls, "class"), Assert.notNull(converter, "converter"));
- for (CommandLine command : interpreter.commands.values()) {
- command.registerConverter(cls, converter);
- }
- return this;
- }
-
- /** Returns the String that separates option names from option values when parsing command line options. {@code '='} by default.
- * @return the String the parser uses to separate option names from option values */
- public String getSeparator() {
- return interpreter.separator;
- }
-
- /** Sets the String the parser uses to separate option names from option values to the specified value.
- * @param separator the String that separates option names from option values */
- public void setSeparator(String separator) {
- interpreter.separator = Assert.notNull(separator, "separator");
- }
- private static boolean empty(String str) { return str == null || str.trim().length() == 0; }
- private static boolean empty(Object[] array) { return array == null || array.length == 0; }
- private static boolean empty(Text txt) { return txt == null || txt.plain.toString().trim().length() == 0; }
- private static String str(String[] arr, int i) { return (arr == null || arr.length == 0) ? "" : arr[i]; }
- private static boolean isBoolean(Class<?> type) { return type == Boolean.class || type == Boolean.TYPE; }
- private static CommandLine toCommandLine(Object obj) { return obj instanceof CommandLine ? (CommandLine) obj : new CommandLine(obj);}
- /**
- * <p>
- * Annotate fields in your class with {@code @Option} and picocli will initialize these fields when matching
- * arguments are specified on the command line.
- * </p><p>
- * For example:
- * </p>
- * <pre>import static picocli.CommandLine.*;
- *
- * public class MyClass {
- * @Parameters(type = File.class, description = "Any number of input files")
- * private List<File> files = new ArrayList<File>();
- *
- * @Option(names = { "-o", "--out" }, description = "Output file (default: print to console)")
- * private File outputFile;
- *
- * @Option(names = { "-v", "--verbose"}, description = "Verbosely list files processed")
- * private boolean verbose;
- *
- * @Option(names = { "-h", "--help", "-?", "-help"}, help = true, description = "Display this help and exit")
- * private boolean help;
- *
- * @Option(names = { "-V", "--version"}, help = true, description = "Display version information and exit")
- * private boolean version;
- * }
- * </pre>
- * <p>
- * A field cannot be annotated with both {@code @Parameters} and {@code @Option} or a
- * {@code ParameterException} is thrown.
- * </p>
- */
- @Retention(RetentionPolicy.RUNTIME)
- @Target(ElementType.FIELD)
- public @interface Option {
- /**
- * One or more option names. At least one option name is required.
- * <p>
- * Different environments have different conventions for naming options, but usually options have a prefix
- * that sets them apart from parameters.
- * Picocli supports all of the below styles. The default separator is {@code '='}, but this can be configured.
- * </p><p>
- * <b>*nix</b>
- * </p><p>
- * In Unix and Linux, options have a short (single-character) name, a long name or both.
- * Short options
- * (<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02">POSIX
- * style</a> are single-character and are preceded by the {@code '-'} character, e.g., {@code `-v'}.
- * <a href="https://www.gnu.org/software/tar/manual/html_node/Long-Options.html">GNU-style</a> long
- * (or <em>mnemonic</em>) options start with two dashes in a row, e.g., {@code `--file'}.
- * </p><p>Picocli supports the POSIX convention that short options can be grouped, with the last option
- * optionally taking a parameter, which may be attached to the option name or separated by a space or
- * a {@code '='} character. The below examples are all equivalent:
- * </p><pre>
- * -xvfFILE
- * -xvf FILE
- * -xvf=FILE
- * -xv --file FILE
- * -xv --file=FILE
- * -x -v --file FILE
- * -x -v --file=FILE
- * </pre><p>
- * <b>DOS</b>
- * </p><p>
- * DOS options mostly have upper case single-character names and start with a single slash {@code '/'} character.
- * Option parameters are separated by a {@code ':'} character. Options cannot be grouped together but
- * must be specified separately. For example:
- * </p><pre>
- * DIR /S /A:D /T:C
- * </pre><p>
- * <b>PowerShell</b>
- * </p><p>
- * Windows PowerShell options generally are a word preceded by a single {@code '-'} character, e.g., {@code `-Help'}.
- * Option parameters are separated by a space or by a {@code ':'} character.
- * </p>
- * @return one or more option names
- */
- String[] names();
-
- /**
- * Indicates whether this option is required. By default this is false.
- * If an option is required, but a user invokes the program without specifying the required option,
- * a {@link MissingParameterException} is thrown from the {@link #parse(String...)} method.
- * @return whether this option is required
- */
- boolean required() default false;
-
- /**
- * Set {@code help=true} if this option should disable validation of the remaining arguments:
- * If the {@code help} option is specified, no error message is generated for missing required options.
- * <p>
- * This attribute is useful for special options like help ({@code -h} and {@code --help} on unix,
- * {@code -?} and {@code -Help} on Windows) or version ({@code -V} and {@code --version} on unix,
- * {@code -Version} on Windows).
- * </p>
- * <p>
- * Note that the {@link #parse(String...)} method will not print help documentation. It will only set
- * the value of the annotated field. It is the responsibility of the caller to inspect the annotated fields
- * and take the appropriate action.
- * </p>
- * @return whether this option disables validation of the other arguments
- */
- boolean help() default false;
-
- /**
- * Set {@code usageHelp=true} if this option allows the user to request usage help. If this option is
- * specified on the command line, picocli will not validate the remaining arguments (so no "missing required
- * option" errors) and the {@link CommandLine#isUsageHelpRequested()} method will return {@code true}.
- * <p>
- * This attribute is useful for special options like help ({@code -h} and {@code --help} on unix,
- * {@code -?} and {@code -Help} on Windows).
- * </p>
- * <p>
- * Note that the {@link #parse(String...)} method will not print usage help documentation. It will only set
- * the value of the annotated field. It is the responsibility of the caller to inspect the annotated fields
- * and take the appropriate action.
- * </p>
- * @return whether this option allows the user to request usage help
- */
- boolean usageHelp() default false;
-
- /**
- * Set {@code versionHelp=true} if this option allows the user to request version information. If this option is
- * specified on the command line, picocli will not validate the remaining arguments (so no "missing required
- * option" errors) and the {@link CommandLine#isVersionHelpRequested()} method will return {@code true}.
- * <p>
- * This attribute is useful for special options like version ({@code -V} and {@code --version} on unix,
- * {@code -Version} on Windows).
- * </p>
- * <p>
- * Note that the {@link #parse(String...)} method will not print version information. It will only set
- * the value of the annotated field. It is the responsibility of the caller to inspect the annotated fields
- * and take the appropriate action.
- * </p>
- * @return whether this option allows the user to request version information
- */
- boolean versionHelp() default false;
-
- /**
- * Description of this option, used when generating the usage documentation.
- * @return the description of this option
- */
- String[] description() default {};
-
- /**
- * Specifies the minimum number of required parameters and the maximum number of accepted parameters.
- * If an option declares a positive arity, and the user specifies an insufficient number of parameters on the
- * command line, a {@link MissingParameterException} is thrown by the {@link #parse(String...)} method.
- * <p>
- * In many cases picocli can deduce the number of required parameters from the field's type.
- * By default, flags (boolean options) have arity zero,
- * and single-valued type fields (String, int, Integer, double, Double, File, Date, etc) have arity one.
- * Generally, fields with types that cannot hold multiple values can omit the {@code arity} attribute.
- * </p><p>
- * Fields used to capture options with arity two or higher should have a type that can hold multiple values,
- * like arrays or Collections. See {@link #type()} for strongly-typed Collection fields.
- * </p><p>
- * For example, if an option has 2 required parameters and any number of optional parameters,
- * specify {@code @Option(names = "-example", arity = "2..*")}.
- * </p>
- * <b>A note on boolean options</b>
- * <p>
- * By default picocli does not expect boolean options (also called "flags" or "switches") to have a parameter.
- * You can make a boolean option take a required parameter by annotating your field with {@code arity="1"}.
- * For example: </p>
- * <pre>@Option(names = "-v", arity = "1") boolean verbose;</pre>
- * <p>
- * Because this boolean field is defined with arity 1, the user must specify either {@code <program> -v false}
- * or {@code <program> -v true}
- * on the command line, or a {@link MissingParameterException} is thrown by the {@link #parse(String...)}
- * method.
- * </p><p>
- * To make the boolean parameter possible but optional, define the field with {@code arity = "0..1"}.
- * For example: </p>
- * <pre>@Option(names="-v", arity="0..1") boolean verbose;</pre>
- * <p>This will accept any of the below without throwing an exception:</p>
- * <pre>
- * -v
- * -v true
- * -v false
- * </pre>
- * @return how many arguments this option requires
- */
- String arity() default "";
-
- /**
- * Specify a {@code paramLabel} for the option parameter to be used in the usage help message. If omitted,
- * picocli uses the field name in fish brackets ({@code '<'} and {@code '>'}) by default. Example:
- * <pre>class Example {
- * @Option(names = {"-o", "--output"}, paramLabel="FILE", description="path of the output file")
- * private File out;
- * @Option(names = {"-j", "--jobs"}, arity="0..1", description="Allow N jobs at once; infinite jobs with no arg.")
- * private int maxJobs = -1;
- * }</pre>
- * <p>By default, the above gives a usage help message like the following:</p><pre>
- * Usage: <main class> [OPTIONS]
- * -o, --output FILE path of the output file
- * -j, --jobs [<maxJobs>] Allow N jobs at once; infinite jobs with no arg.
- * </pre>
- * @return name of the option parameter used in the usage help message
- */
- String paramLabel() default "";
-
- /**
- * <p>
- * Specify a {@code type} if the annotated field is a {@code Collection} that should hold objects other than Strings.
- * </p><p>
- * If the field's type is a {@code Collection}, the generic type parameter of the collection is erased and
- * cannot be determined at runtime. Specify a {@code type} attribute to store values other than String in
- * the Collection. Picocli will use the {@link ITypeConverter}
- * that is {@linkplain #registerConverter(Class, ITypeConverter) registered} for that type to convert
- * the raw String values before they are added to the collection.
- * </p><p>
- * When the field's type is an array, the {@code type} attribute is ignored: the values will be converted
- * to the array component type and the array will be replaced with a new instance containing both the old and
- * the new values. </p>
- * @return the type to convert the raw String values to before adding them to the Collection
- */
- Class<?> type() default String.class;
-
- /**
- * Specify a regular expression to use to split option parameter values before applying them to the field.
- * All elements resulting from the split are added to the array or Collection. Ignored for single-value fields.
- * @return a regular expression to split option parameter values or {@code ""} if the value should not be split
- * @see String#split(String)
- */
- String split() default "";
-
- /**
- * Set {@code hidden=true} if this option should not be included in the usage documentation.
- * @return whether this option should be excluded from the usage message
- */
- boolean hidden() default false;
- }
- /**
- * <p>
- * Fields annotated with {@code @Parameters} will be initialized with positional parameters. By specifying the
- * {@link #index()} attribute you can pick which (or what range) of the positional parameters to apply. If no index
- * is specified, the field will get all positional parameters (so it should be an array or a collection).
- * </p><p>
- * When parsing the command line arguments, picocli first tries to match arguments to {@link Option Options}.
- * Positional parameters are the arguments that follow the options, or the arguments that follow a "--" (double
- * dash) argument on the command line.
- * </p><p>
- * For example:
- * </p>
- * <pre>import static picocli.CommandLine.*;
- *
- * public class MyCalcParameters {
- * @Parameters(type = BigDecimal.class, description = "Any number of input numbers")
- * private List<BigDecimal> files = new ArrayList<BigDecimal>();
- *
- * @Option(names = { "-h", "--help", "-?", "-help"}, help = true, description = "Display this help and exit")
- * private boolean help;
- * }
- * </pre><p>
- * A field cannot be annotated with both {@code @Parameters} and {@code @Option} or a {@code ParameterException}
- * is thrown.</p>
- */
- @Retention(RetentionPolicy.RUNTIME)
- @Target(ElementType.FIELD)
- public @interface Parameters {
- /** Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this
- * field. For array or Collection fields, you can also specify an index range ("0..3", or "2..*", etc.) to assign
- * a subset of the command line arguments to this field. The default is "*", meaning all command line arguments.
- * @return an index or range specifying which of the command line arguments should be assigned to this field
- */
- String index() default "*";
-
- /** Description of the parameter(s), used when generating the usage documentation.
- * @return the description of the parameter(s)
- */
- String[] description() default {};
-
- /**
- * Specifies the minimum number of required parameters and the maximum number of accepted parameters. If a
- * positive arity is declared, and the user specifies an insufficient number of parameters on the command line,
- * {@link MissingParameterException} is thrown by the {@link #parse(String...)} method.
- * <p>The default depends on the type of the parameter: booleans require no parameters, arrays and Collections
- * accept zero to any number of parameters, and any other type accepts one parameter.</p>
- * @return the range of minimum and maximum parameters accepted by this command
- */
- String arity() default "";
-
- /**
- * Specify a {@code paramLabel} for the parameter to be used in the usage help message. If omitted,
- * picocli uses the field name in fish brackets ({@code '<'} and {@code '>'}) by default. Example:
- * <pre>class Example {
- * @Parameters(paramLabel="FILE", description="path of the input FILE(s)")
- * private File[] inputFiles;
- * }</pre>
- * <p>By default, the above gives a usage help message like the following:</p><pre>
- * Usage: <main class> [FILE...]
- * [FILE...] path of the input FILE(s)
- * </pre>
- * @return name of the positional parameter used in the usage help message
- */
- String paramLabel() default "";
-
- /**
- * <p>
- * Specify a {@code type} if the annotated field is a {@code Collection} that should hold objects other than Strings.
- * </p><p>
- * If the field's type is a {@code Collection}, the generic type parameter of the collection is erased and
- * cannot be determined at runtime. Specify a {@code type} attribute to store values other than String in
- * the Collection. Picocli will use the {@link ITypeConverter}
- * that is {@linkplain #registerConverter(Class, ITypeConverter) registered} for that type to convert
- * the raw String values before they are added to the collection.
- * </p><p>
- * When the field's type is an array, the {@code type} attribute is ignored: the values will be converted
- * to the array component type and the array will be replaced with a new instance containing both the old and
- * the new values. </p>
- * @return the type to convert the raw String values to before adding them to the Collection
- */
- Class<?> type() default String.class;
-
- /**
- * Specify a regular expression to use to split positional parameter values before applying them to the field.
- * All elements resulting from the split are added to the array or Collection. Ignored for single-value fields.
- * @return a regular expression to split operand values or {@code ""} if the value should not be split
- * @see String#split(String)
- */
- String split() default "";
-
- /**
- * Set {@code hidden=true} if this parameter should not be included in the usage message.
- * @return whether this parameter should be excluded from the usage message
- */
- boolean hidden() default false;
- }
-
- /**
- * <p>Annotate your class with {@code @Command} when you want more control over the format of the generated help
- * message.
- * </p><pre>
- * @Command(name = "Encrypt",
- * description = "Encrypt FILE(s), or standard input, to standard output or to the output file.",
- * footer = "Copyright (c) 2017")
- * public class Encrypt {
- * @Parameters(paramLabel = "FILE", type = File.class, description = "Any number of input files")
- * private List<File> files = new ArrayList<File>();
- *
- * @Option(names = { "-o", "--out" }, description = "Output file (default: print to console)")
- * private File outputFile;
- * }</pre>
- * <p>
- * The structure of a help message looks like this:
- * </p><ul>
- * <li>[header]</li>
- * <li>[synopsis]: {@code Usage: <commandName> [OPTIONS] [FILE...]}</li>
- * <li>[description]</li>
- * <li>[parameter list]: {@code [FILE...] Any number of input files}</li>
- * <li>[option list]: {@code -h, --help prints this help message and exits}</li>
- * <li>[footer]</li>
- * </ul> */
- @Retention(RetentionPolicy.RUNTIME)
- @Target(ElementType.TYPE)
- public @interface Command {
- /** Program name to show in the synopsis. If omitted, {@code "<main class>"} is used.
- * For {@linkplain #subcommands() declaratively added} subcommands, this attribute is also used
- * by the parser to recognize subcommands in the command line arguments.
- * @return the program name to show in the synopsis
- * @see Help#commandName */
- String name() default "<main class>";
-
- /** A list of classes to instantiate and register as subcommands. When registering subcommands declaratively
- * like this, you don't need to call the {@link CommandLine#addSubcommand(String, Object)} method. For example, this:
- * <pre>
- * @Command(subcommands = {
- * GitStatus.class,
- * GitCommit.class,
- * GitBranch.class })
- * public class Git { ... }
- *
- * CommandLine commandLine = new CommandLine(new Git());
- * </pre> is equivalent to this:
- * <pre>
- * // alternative: programmatically add subcommands.
- * // NOTE: in this case there should be no `subcommands` attribute on the @Command annotation.
- * @Command public class Git { ... }
- *
- * CommandLine commandLine = new CommandLine(new Git())
- * .addSubcommand("status", new GitStatus())
- * .addSubcommand("commit", new GitCommit())
- * .addSubcommand("branch", new GitBranch());
- * </pre>
- * @return the declaratively registered subcommands of this command, or an empty array if none
- * @see CommandLine#addSubcommand(String, Object)
- * @since 0.9.8
- */
- Class<?>[] subcommands() default {};
-
- /** String that separates options from option parameters. Default is {@code "="}. Spaces are also accepted.
- * @return the string that separates options from option parameters, used both when parsing and when generating usage help
- * @see Help#separator
- * @see CommandLine#setSeparator(String) */
- String separator() default "=";
-
- /** Version information for this command, to print to the console when the user specifies an
- * {@linkplain Option#versionHelp() option} to request version help. This is not part of the usage help message.
- *
- * @return a string or an array of strings with version information about this command.
- * @since 0.9.8
- * @see CommandLine#printVersionHelp(PrintStream)
- */
- String[] version() default {};
-
- /** Set the heading preceding the header section. May contain embedded {@linkplain java.util.Formatter format specifiers}.
- * @return the heading preceding the header section
- * @see Help#headerHeading(Object...) */
- String headerHeading() default "";
-
- /** Optional summary description of the command, shown before the synopsis.
- * @return summary description of the command
- * @see Help#header
- * @see Help#header(Object...) */
- String[] header() default {};
-
- /** Set the heading preceding the synopsis text. May contain embedded
- * {@linkplain java.util.Formatter format specifiers}. The default heading is {@code "Usage: "} (without a line
- * break between the heading and the synopsis text).
- * @return the heading preceding the synopsis text
- * @see Help#synopsisHeading(Object...) */
- String synopsisHeading() default "Usage: ";
-
- /** Specify {@code true} to generate an abbreviated synopsis like {@code "<main> [OPTIONS] [PARAMETERS...]"}.
- * By default, a detailed synopsis with individual option names and parameters is generated.
- * @return whether the synopsis should be abbreviated
- * @see Help#abbreviateSynopsis
- * @see Help#abbreviatedSynopsis()
- * @see Help#detailedSynopsis(Comparator, boolean) */
- boolean abbreviateSynopsis() default false;
-
- /** Specify one or more custom synopsis lines to display instead of an auto-generated synopsis.
- * @return custom synopsis text to replace the auto-generated synopsis
- * @see Help#customSynopsis
- * @see Help#customSynopsis(Object...) */
- String[] customSynopsis() default {};
-
- /** Set the heading preceding the description section. May contain embedded {@linkplain java.util.Formatter format specifiers}.
- * @return the heading preceding the description section
- * @see Help#descriptionHeading(Object...) */
- String descriptionHeading() default "";
-
- /** Optional text to display between the synopsis line(s) and the list of options.
- * @return description of this command
- * @see Help#description
- * @see Help#description(Object...) */
- String[] description() default {};
-
- /** Set the heading preceding the parameters list. May contain embedded {@linkplain java.util.Formatter format specifiers}.
- * @return the heading preceding the parameters list
- * @see Help#parameterListHeading(Object...) */
- String parameterListHeading() default "";
-
- /** Set the heading preceding the options list. May contain embedded {@linkplain java.util.Formatter format specifiers}.
- * @return the heading preceding the options list
- * @see Help#optionListHeading(Object...) */
- String optionListHeading() default "";
-
- /** Specify {@code false} to show Options in declaration order. The default is to sort alphabetically.
- * @return whether options should be shown in alphabetic order.
- * @see Help#sortOptions */
- boolean sortOptions() default true;
-
- /** Prefix required options with this character in the options list. The default is no marker: the synopsis
- * indicates which options and parameters are required.
- * @return the character to show in the options list to mark required options
- * @see Help#requiredOptionMarker */
- char requiredOptionMarker() default ' ';
-
- /** Specify {@code true} to show default values in the description column of the options list (except for
- * boolean options). False by default.
- * @return whether the default values for options and parameters should be shown in the description column
- * @see Help#showDefaultValues */
- boolean showDefaultValues() default false;
-
- /** Set the heading preceding the subcommands list. May contain embedded {@linkplain java.util.Formatter format specifiers}.
- * The default heading is {@code "Commands:%n"} (with a line break at the end).
- * @return the heading preceding the subcommands list
- * @see Help#commandListHeading(Object...) */
- String commandListHeading() default "Commands:%n";
-
- /** Set the heading preceding the footer section. May contain embedded {@linkplain java.util.Formatter format specifiers}.
- * @return the heading preceding the footer section
- * @see Help#footerHeading(Object...) */
- String footerHeading() default "";
-
- /** Optional text to display after the list of options.
- * @return text to display after the list of options
- * @see Help#footer
- * @see Help#footer(Object...) */
- String[] footer() default {};
- }
- /**
- * <p>
- * When parsing command line arguments and initializing
- * fields annotated with {@link Option @Option} or {@link Parameters @Parameters},
- * String values can be converted to any type for which a {@code ITypeConverter} is registered.
- * </p><p>
- * This interface defines the contract for classes that know how to convert a String into some domain object.
- * Custom converters can be registered with the {@link #registerConverter(Class, ITypeConverter)} method.
- * </p><p>
- * Java 8 lambdas make it easy to register custom type converters:
- * </p>
- * <pre>
- * commandLine.registerConverter(java.nio.file.Path.class, s -> java.nio.file.Paths.get(s));
- * commandLine.registerConverter(java.time.Duration.class, s -> java.time.Duration.parse(s));</pre>
- * <p>
- * Built-in type converters are pre-registered for the following java 1.5 types:
- * </p>
- * <ul>
- * <li>all primitive types</li>
- * <li>all primitive wrapper types: Boolean, Byte, Character, Double, Float, Integer, Long, Short</li>
- * <li>any enum</li>
- * <li>java.io.File</li>
- * <li>java.math.BigDecimal</li>
- * <li>java.math.BigInteger</li>
- * <li>java.net.InetAddress</li>
- * <li>java.net.URI</li>
- * <li>java.net.URL</li>
- * <li>java.nio.charset.Charset</li>
- * <li>java.sql.Time</li>
- * <li>java.util.Date</li>
- * <li>java.util.UUID</li>
- * <li>java.util.regex.Pattern</li>
- * <li>StringBuilder</li>
- * <li>CharSequence</li>
- * <li>String</li>
- * </ul>
- * @param <K> the type of the object that is the result of the conversion
- */
- public interface ITypeConverter<K> {
- /**
- * Converts the specified command line argument value to some domain object.
- * @param value the command line argument String value
- * @return the resulting domain object
- * @throws Exception an exception detailing what went wrong during the conversion
- */
- K convert(String value) throws Exception;
- }
- /** Describes the number of parameters required and accepted by an option or a positional parameter.
- * @since 0.9.7
- */
- public static class Range implements Comparable<Range> {
- /** Required number of parameters for an option or positional parameter. */
- public final int min;
- /** Maximum accepted number of parameters for an option or positional parameter. */
- public final int max;
- public final boolean isVariable;
- private final boolean isUnspecified;
- private final String originalValue;
-
- /** Constructs a new Range object with the specified parameters.
- * @param min minimum number of required parameters
- * @param max maximum number of allowed parameters (or Integer.MAX_VALUE if variable)
- * @param variable {@code true} if any number or parameters is allowed, {@code false} otherwise
- * @param unspecified {@code true} if no arity was specified on the option/parameter (value is based on type)
- * @param originalValue the original value that was specified on the option or parameter
- */
- public Range(int min, int max, boolean variable, boolean unspecified, String originalValue) {
- this.min = min;
- this.max = max;
- this.isVariable = variable;
- this.isUnspecified = unspecified;
- this.originalValue = originalValue;
- }
- /** Returns a new {@code Range} based on the {@link Option#arity()} annotation on the specified field,
- * or the field type's default arity if no arity was specified.
- * @param field the field whose Option annotation to inspect
- * @return a new {@code Range} based on the Option arity annotation on the specified field */
- public static Range optionArity(Field field) {
- return field.isAnnotationPresent(Option.class)
- ? adjustForType(Range.valueOf(field.getAnnotation(Option.class).arity()), field)
- : new Range(0, 0, false, true, "0");
- }
- /** Returns a new {@code Range} based on the {@link Parameters#arity()} annotation on the specified field,
- * or the field type's default arity if no arity was specified.
- * @param field the field whose Parameters annotation to inspect
- * @return a new {@code Range} based on the Parameters arity annotation on the specified field */
- public static Range parameterArity(Field field) {
- return field.isAnnotationPresent(Parameters.class)
- ? adjustForType(Range.valueOf(field.getAnnotation(Parameters.class).arity()), field)
- : new Range(0, 0, false, true, "0");
- }
- /** Returns a new {@code Range} based on the {@link Parameters#index()} annotation on the specified field.
- * @param field the field whose Parameters annotation to inspect
- * @return a new {@code Range} based on the Parameters index annotation on the specified field */
- public static Range parameterIndex(Field field) {
- return field.isAnnotationPresent(Parameters.class)
- ? Range.valueOf(field.getAnnotation(Parameters.class).index())
- : new Range(0, 0, false, true, "0");
- }
- static Range adjustForType(Range result, Field field) {
- return result.isUnspecified ? defaultArity(field.getType()) : result;
- }
- /** Returns a new {@code Range} based on the specified type: booleans have arity 0, arrays or Collections have
- * arity "0..*", and other types have arity 1.
- * @param type the type whose default arity to return
- * @return a new {@code Range} indicating the default arity of the specified type */
- public static Range defaultArity(Class<?> type) {
- if (isBoolean(type)) {
- return Range.valueOf("0");
- } else if (type.isArray() || Collection.class.isAssignableFrom(type)) {
- return Range.valueOf("0..*");
- }
- return Range.valueOf("1");// for single-valued fields
- }
- /** Leniently parses the specified String as an {@code Range} value and return the result. A range string can
- * be a fixed integer value or a range of the form {@code MIN_VALUE + ".." + MAX_VALUE}. If the
- * {@code MIN_VALUE} string is not numeric, the minimum is zero. If the {@code MAX_VALUE} is not numeric, the
- * range is taken to be variable and the maximum is {@code Integer.MAX_VALUE}.
- * @param range the value range string to parse
- * @return a new {@code Range} value */
- public static Range valueOf(String range) {
- range = range.trim();
- boolean unspecified = range.length() == 0 || range.startsWith(".."); // || range.endsWith("..");
- int min = -1, max = -1;
- boolean variable = false;
- int dots = -1;
- if ((dots = range.indexOf("..")) >= 0) {
- min = parseInt(range.substring(0, dots), 0);
- max = parseInt(range.substring(dots + 2), Integer.MAX_VALUE);
- variable = max == Integer.MAX_VALUE;
- } else {
- max = parseInt(range, Integer.MAX_VALUE);
- variable = max == Integer.MAX_VALUE;
- min = variable ? 0 : max;
- }
- Range result = new Range(min, max, variable, unspecified, range);
- return result;
- }
- private static int parseInt(String str, int defaultValue) {
- try {
- return Integer.parseInt(str);
- } catch (Exception ex) {
- return defaultValue;
- }
- }
- /** Returns a new Range object with the {@code min} value replaced by the specified value.
- * The {@code max} of the returned Range is guaranteed not to be less than the new {@code min} value.
- * @param newMin the {@code min} value of the returned Range object
- * @return a new Range object with the specified {@code min} value */
- public Range min(int newMin) { return new Range(newMin, Math.max(newMin, max), isVariable, isUnspecified, originalValue); }
-
- /** Returns a new Range object with the {@code max} value replaced by the specified value.
- * The {@code min} of the returned Range is guaranteed not to be greater than the new {@code max} value.
- * @param newMax the {@code max} value of the returned Range object
- * @return a new Range object with the specified {@code max} value */
- public Range max(int newMax) { return new Range(Math.min(min, newMax), newMax, isVariable, isUnspecified, originalValue); }
-
- public boolean equals(Object object) {
- if (!(object instanceof Range)) { return false; }
- Range other = (Range) object;
- return other.max == this.max && other.min == this.min && other.isVariable == this.isVariable;
- }
- public int hashCode() {
- return ((17 * 37 + max) * 37 + min) * 37 + (isVariable ? 1 : 0);
- }
- public String toString() {
- return min == max ? String.valueOf(min) : min + ".." + (isVariable ? "*" : max);
- }
- public int compareTo(Range other) {
- int result = min - other.min;
- return (result == 0) ? max - other.max : result;
- }
- }
- private static void init(Class<?> cls,
- List<Field> requiredFields,
- Map<String, Field> optionName2Field,
- Map<Character, Field> singleCharOption2Field,
- List<Field> positionalParametersFields) {
- Field[] declaredFields = cls.getDeclaredFields();
- for (Field field : declaredFields) {
- field.setAccessible(true);
- if (field.isAnnotationPresent(Option.class)) {
- Option option = field.getAnnotation(Option.class);
- if (option.required()) {
- requiredFields.add(field);
- }
- for (String name : option.names()) { // cannot be null or empty
- Field existing = optionName2Field.put(name, field);
- if (existing != null && existing != field) {
- throw DuplicateOptionAnnotationsException.create(name, field, existing);
- }
- if (name.length() == 2 && name.startsWith("-")) {
- char flag = name.charAt(1);
- Field existing2 = singleCharOption2Field.put(flag, field);
- if (existing2 != null && existing2 != field) {
- throw DuplicateOptionAnnotationsException.create(name, field, existing2);
- }
- }
- }
- }
- if (field.isAnnotationPresent(Parameters.class)) {
- if (field.isAnnotationPresent(Option.class)) {
- throw new ParameterException("A field can be either @Option or @Parameters, but '"
- + field.getName() + "' is both.");
- }
- positionalParametersFields.add(field);
- Range arity = Range.parameterArity(field);
- if (arity.min > 0) {
- requiredFields.add(field);
- }
- }
- }
- }
- static void validatePositionalParameters(List<Field> positionalParametersFields) {
- int min = 0;
- for (Field field : positionalParametersFields) {
- Range index = Range.parameterIndex(field);
- if (index.min > min) {
- throw new ParameterIndexGapException("Missing field annotated with @Parameter(index=" + min +
- "). Nearest field '" + field.getName() + "' has index=" + index.min);
- }
- min = Math.max(min, index.max);
- min = min == Integer.MAX_VALUE ? min : min + 1;
- }
- }
- private static <T> Stack<T> reverse(Stack<T> stack) {
- Collections.reverse(stack);
- return stack;
- }
- /**
- * Helper class responsible for processing command line arguments.
- */
- private class Interpreter {
- private final Map<String, CommandLine> commands = new LinkedHashMap<String, CommandLine>();
- private final Map<Class<?>, ITypeConverter<?>> converterRegistry = new HashMap<Class<?>, ITypeConverter<?>>();
- private final Map<String, Field> optionName2Field = new HashMap<String, Field>();
- private final Map<Character, Field> singleCharOption2Field = new HashMap<Character, Field>();
- private final List<Field> requiredFields = new ArrayList<Field>();
- private final List<Field> positionalParametersFields = new ArrayList<Field>();
- private final Object command;
- private boolean isHelpRequested;
- private String separator = "=";
-
- Interpreter(Object command) {
- converterRegistry.put(Path.class, new BuiltIn.PathConverter());
- converterRegistry.put(String.class, new BuiltIn.StringConverter());
- converterRegistry.put(StringBuilder.class, new BuiltIn.StringBuilderConverter());
- converterRegistry.put(CharSequence.class, new BuiltIn.CharSequenceConverter());
- converterRegistry.put(Byte.class, new BuiltIn.ByteConverter());
- converterRegistry.put(Byte.TYPE, new BuiltIn.ByteConverter());
- converterRegistry.put(Boolean.class, new BuiltIn.BooleanConverter());
- converterRegistry.put(Boolean.TYPE, new BuiltIn.BooleanConverter());
- converterRegistry.put(Character.class, new BuiltIn.CharacterConverter());
- converterRegistry.put(Character.TYPE, new BuiltIn.CharacterConverter());
- converterRegistry.put(Short.class, new BuiltIn.ShortConverter());
- converterRegistry.put(Short.TYPE, new BuiltIn.ShortConverter());
- converterRegistry.put(Integer.class, new BuiltIn.IntegerConverter());
- converterRegistry.put(Integer.TYPE, new BuiltIn.IntegerConverter());
- converterRegistry.put(Long.class, new BuiltIn.LongConverter());
- converterRegistry.put(Long.TYPE, new BuiltIn.LongConverter());
- converterRegistry.put(Float.class, new BuiltIn.FloatConverter());
- converterRegistry.put(Float.TYPE, new BuiltIn.FloatConverter());
- converterRegistry.put(Double.class, new BuiltIn.DoubleConverter());
- converterRegistry.put(Double.TYPE, new BuiltIn.DoubleConverter());
- converterRegistry.put(File.class, new BuiltIn.FileConverter());
- converterRegistry.put(URI.class, new BuiltIn.URIConverter());
- converterRegistry.put(URL.class, new BuiltIn.URLConverter());
- converterRegistry.put(Date.class, new BuiltIn.ISO8601DateConverter());
- converterRegistry.put(Time.class, new BuiltIn.ISO8601TimeConverter());
- converterRegistry.put(BigDecimal.class, new BuiltIn.BigDecimalConverter());
- converterRegistry.put(BigInteger.class, new BuiltIn.BigIntegerConverter());
- converterRegistry.put(Charset.class, new BuiltIn.CharsetConverter());
- converterRegistry.put(InetAddress.class, new BuiltIn.InetAddressConverter());
- converterRegistry.put(Pattern.class, new BuiltIn.PatternConverter());
- converterRegistry.put(UUID.class, new BuiltIn.UUIDConverter());
-
- this.command = Assert.notNull(command, "command");
- Class<?> cls = command.getClass();
- String declaredSeparator = null;
- boolean hasCommandAnnotation = false;
- while (cls != null) {
- init(cls, requiredFields, optionName2Field, singleCharOption2Field, positionalParametersFields);
- if (cls.isAnnotationPresent(Command.class)) {
- hasCommandAnnotation = true;
- Command cmd = cls.getAnnotation(Command.class);
- declaredSeparator = (declaredSeparator == null) ? cmd.separator() : declaredSeparator;
- CommandLine.this.versionLines.addAll(Arrays.asList(cmd.version()));
-
- for (Class<?> sub : cmd.subcommands()) {
- Command subCommand = sub.getAnnotation(Command.class);
- if (subCommand == null || Help.DEFAULT_COMMAND_NAME.equals(subCommand.name())) {
- throw new IllegalArgumentException("Subcommand " + sub.getName() +
- " is missing the mandatory @Command annotation with a 'name' attribute");
- }
- try {
- Constructor<?> constructor = sub.getDeclaredConstructor();
- constructor.setAccessible(true);
- CommandLine commandLine = toCommandLine(constructor.newInstance());
- commandLine.parent = CommandLine.this;
- commands.put(subCommand.name(), commandLine);
- }
- catch (IllegalArgumentException ex) { throw ex; }
- catch (NoSuchMethodException ex) { throw new IllegalArgumentException("Cannot instantiate subcommand " +
- sub.getName() + ": the class has no constructor", ex); }
- catch (Exception ex) {
- throw new IllegalStateException("Could not instantiate and add subcommand " +
- sub.getName() + ": " + ex, ex);
- }
- }
- }
- cls = cls.getSuperclass();
- }
- separator = declaredSeparator != null ? declaredSeparator : separator;
- Collections.sort(positionalParametersFields, new PositionalParametersSorter());
- validatePositionalParameters(positionalParametersFields);
-
- if (positionalParametersFields.isEmpty() && optionName2Field.isEmpty() && !hasCommandAnnotation) {
- throw new IllegalArgumentException(command + " (" + command.getClass() +
- ") is not a command: it has no @Command, @Option or @Parameters annotations");
- }
- }
-
- /**
- * Entry point into parsing command line arguments.
- * @param args the command line arguments
- * @return a list with all commands and subcommands initialized by this method
- * @throws ParameterException if the specified command line arguments are invalid
- */
- List<CommandLine> parse(String... args) {
- Assert.notNull(args, "argument array");
- Stack<String> arguments = new Stack<String>();
- for (int i = args.length - 1; i >= 0; i--) {
- arguments.push(args[i]);
- }
- List<CommandLine> result = new ArrayList<CommandLine>();
- parse(result, arguments, args);
- return result;
- }
-
- private void parse(List<CommandLine> parsedCommands, Stack<String> argumentStack, String[] originalArgs) {
- // first reset any state in case this CommandLine instance is being reused
- isHelpRequested = false;
- CommandLine.this.versionHelpRequested = false;
- CommandLine.this.usageHelpRequested = false;
-
- parsedCommands.add(CommandLine.this);
- List<Field> required = new ArrayList<Field>(requiredFields);
- Set<Field> initialized = new HashSet<Field>();
- Collections.sort(required, new PositionalParametersSorter());
- try {
- processArguments(parsedCommands, argumentStack, required, initialized, originalArgs);
- } catch (ParameterException ex) {
- throw ex;
- } catch (Exception ex) {
- int offendingArgIndex = originalArgs.length - argumentStack.size();
- String arg = offendingArgIndex >= 0 && offendingArgIndex < originalArgs.length ? originalArgs[offendingArgIndex] : "?";
- throw ParameterException.create(ex, arg, argumentStack.size(), originalArgs);
- }
- if (!isAnyHelpRequested() && !required.isEmpty()) {
- if (required.get(0).isAnnotationPresent(Option.class)) {
- throw MissingParameterException.create(required);
- } else {
- try {
- processPositionalParameters0(required, true, new Stack<String>());
- } catch (ParameterException ex) { throw ex;
- } catch (Exception ex) { throw new IllegalStateException("Internal error: " + ex, ex); }
- }
- }
- }
-
- private void processArguments(List<CommandLine> parsedCommands,
- Stack<String> args,
- Collection<Field> required,
- Set<Field> initialized,
- String[] originalArgs) throws Exception {
- // arg must be one of:
- // 1. the "--" double dash separating options from positional arguments
- // 1. a stand-alone flag, like "-v" or "--verbose": no value required, must map to boolean or Boolean field
- // 2. a short option followed by an argument, like "-f file" or "-ffile": may map to any type of field
- // 3. a long option followed by an argument, like "-file out.txt" or "-file=out.txt"
- // 3. one or more remaining arguments without any associated options. Must be the last in the list.
- // 4. a combination of stand-alone options, like "-vxr". Equivalent to "-v -x -r", "-v true -x true -r true"
- // 5. a combination of stand-alone options and one option with an argument, like "-vxrffile"
-
- while (!args.isEmpty()) {
- String arg = args.pop();
-
- // Double-dash separates options from positional arguments.
- // If found, then interpret the remaining args as positional parameters.
- if ("--".equals(arg)) {
- processPositionalParameters(required, args);
- return; // we are done
- }
-
- // if we find another command, we are done with the current command
- if (commands.containsKey(arg)) {
- if (!isHelpRequested && !required.isEmpty()) { // ensure current command portion is valid
- throw MissingParameterException.create(required);
- }
- commands.get(arg).interpreter.parse(parsedCommands, args, originalArgs);
- return; // remainder done by the command
- }
-
- // First try to interpret the argument as a single option (as opposed to a compact group of options).
- // A single option may be without option parameters, like "-v" or "--verbose" (a boolean value),
- // or an option may have one or more option parameters.
- // A parameter may be attached to the option.
- boolean paramAttachedToOption = false;
- int separatorIndex = arg.indexOf(separator);
- if (separatorIndex > 0) {
- String key = arg.substring(0, separatorIndex);
- // be greedy. Consume the whole arg as an option if possible.
- if (optionName2Field.containsKey(key) && !optionName2Field.containsKey(arg)) {
- paramAttachedToOption = true;
- String optionParam = arg.substring(separatorIndex + separator.length());
- args.push(optionParam);
- arg = key;
- }
- }
- if (optionName2Field.containsKey(arg)) {
- processStandaloneOption(required, initialized, arg, args, paramAttachedToOption);
- }
- // Compact (single-letter) options can be grouped with other options or with an argument.
- // only single-letter options can be combined with other options or with an argument
- else if (arg.length() > 2 && arg.startsWith("-")) {
- processClusteredShortOptions(required, initialized, arg, args);
- }
- // The argument could not be interpreted as an option.
- // We take this to mean that the remainder are positional arguments
- else {
- args.push(arg);
- processPositionalParameters(required, args);
- return;
- }
- }
- }
-
- private void processPositionalParameters(Collection<Field> required, Stack<String> args) throws Exception {
- processPositionalParameters0(required, false, args);
- if (!args.empty()) {
- handleUnmatchedArguments(args);
- return;
- };
- }
-
- private void handleUnmatchedArguments(Stack<String> args) {
- if (!isUnmatchedArgumentsAllowed()) { throw new UnmatchedArgumentException(args); }
- while (!args.isEmpty()) { unmatchedArguments.add(args.pop()); } // addAll would give args in reverse order
- }
-
- private void processPositionalParameters0(Collection<Field> required, boolean validateOnly, Stack<String> args) throws Exception {
- int max = -1;
- for (Field positionalParam : positionalParametersFields) {
- Range indexRange = Range.parameterIndex(positionalParam);
- max = Math.max(max, indexRange.max);
- @SuppressWarnings("unchecked")
- Stack<String> argsCopy = reverse((Stack<String>) args.clone());
- if (!indexRange.isVariable) {
- for (int i = argsCopy.size() - 1; i > indexRange.max; i--) {
- argsCopy.removeElementAt(i);
- }
- }
- Collections.reverse(argsCopy);
- for (int i = 0; i < indexRange.min && !argsCopy.isEmpty(); i++) { argsCopy.pop(); }
- Range arity = Range.parameterArity(positionalParam);
- assertNoMissingParameters(positionalParam, arity.min, argsCopy);
- if (!validateOnly) {
- applyOption(positionalParam, Parameters.class, arity, false, argsCopy, null);
- required.remove(positionalParam);
- }
- }
- // remove processed args from the stack
- if (!validateOnly && !positionalParametersFields.isEmpty()) {
- int processedArgCount = Math.min(args.size(), max < Integer.MAX_VALUE ? max + 1 : Integer.MAX_VALUE);
- for (int i = 0; i < processedArgCount; i++) { args.pop(); }
- }
- }
-
- private void processStandaloneOption(Collection<Field> required,
- Set<Field> initialized,
- String arg,
- Stack<String> args,
- boolean paramAttachedToKey) throws Exception {
- Field field = optionName2Field.get(arg);
- required.remove(field);
- Range arity = Range.optionArity(field);
- if (paramAttachedToKey) {
- arity = arity.min(Math.max(1, arity.min)); // if key=value, minimum arity is at least 1
- }
- applyOption(field, Option.class, arity, paramAttachedToKey, args, initialized);
- }
-
- private void processClusteredShortOptions(Collection<Field> required,
- Set<Field> initialized,
- String arg,
- Stack<String> args)
- throws Exception {
- String prefix = arg.substring(0, 1);
- String cluster = arg.substring(1);
- boolean paramAttachedToOption = true;
- do {
- if (cluster.length() > 0 && singleCharOption2Field.containsKey(cluster.charAt(0))) {
- Field field = singleCharOption2Field.get(cluster.charAt(0));
- required.remove(field);
- cluster = cluster.length() > 0 ? cluster.substring(1) : "";
- paramAttachedToOption = cluster.length() > 0;
- Range arity = Range.optionArity(field);
- if (cluster.startsWith(separator)) {// attached with separator, like -f=FILE or -v=true
- cluster = cluster.substring(separator.length());
- arity = arity.min(Math.max(1, arity.min)); // if key=value, minimum arity is at least 1
- }
- args.push(cluster); // interpret remainder as option parameter (CAUTION: may be empty string!)
- // arity may be >= 1, or
- // arity <= 0 && !cluster.startsWith(separator)
- // e.g., boolean @Option("-v", arity=0, varargs=true); arg "-rvTRUE", remainder cluster="TRUE"
- int consumed = applyOption(field, Option.class, arity, paramAttachedToOption, args, initialized);
- // only return if cluster (and maybe more) was consumed, otherwise continue do-while loop
- if (consumed > 0) {
- return;
- }
- cluster = args.pop();
- } else { // cluster is empty || cluster.charAt(0) is not a short option key
- if (cluster.length() == 0) { // we finished parsing a group of short options like -rxv
- return; // return normally and parse the next arg
- }
- // We get here when the remainder of the cluster group is neither an option,
- // nor a parameter that the last option could consume.
- if (arg.endsWith(cluster)) {
- // remainder was part of a clustered group that could not be completely parsed
- args.push(paramAttachedToOption ? prefix + cluster : cluster);
- handleUnmatchedArguments(args);
- }
- args.push(cluster);
- processPositionalParameters(required, args);
- return;
- }
- } while (true);
- }
-
- private int applyOption(Field field,
- Class<?> annotation,
- Range arity,
- boolean valueAttachedToOption,
- Stack<String> args,
- Set<Field> initialized) throws Exception {
- updateHelpRequested(field);
- if (!args.isEmpty() && args.peek().length() == 0 &
<TRUNCATED>