Thank you for retracting your -1, Gary. All, Would core.tools be a better place for this package, just core, or is core.util okay?
On Tue, Aug 15, 2017 at 3:03 AM, Gary Gregory <garydgreg...@gmail.com> wrote: > Can we please avoid "util" packages, that just tells me "I can't be > bothered to think of a good name". Just remove the "util" level IMO. > > Gary > > On Mon, Aug 14, 2017 at 12:02 PM, Gary Gregory <garydgreg...@gmail.com> > wrote: > > > Ugh, not a fan, but I'll retract my -1. > > > > "a single class", yes, but a 4000 line class. > > > > Gary > > > > On Mon, Aug 14, 2017 at 11:06 AM, Matt Sicker <boa...@gmail.com> wrote: > > > >> Embedding a single class? I don't see the problem with that. We do it > with > >> several Commons classes. > >> > >> On 14 August 2017 at 11:59, Gary Gregory <garydgreg...@gmail.com> > wrote: > >> > >> > Wait a minute? We are embedding a third party jar? Yuk! -1, sorry that > >> is > >> > not what I thought was happening. > >> > > >> > Gary > >> > > >> > On Aug 14, 2017 10:18, <rpo...@apache.org> wrote: > >> > > >> > > http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/ > >> > > c2818bec/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 > >> > > new file mode 100644 > >> > > index 0000000..5c4e9cc > >> > > --- /dev/null > >> > > +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/ > >> > > util/picocli/CommandLine.java > >> > > @@ -0,0 +1,3900 @@ > >> > > +/* > >> > > + * 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/#_us > >> age_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.or > >> g/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/soft > >> ware/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(fi > >> eld.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 DuplicateOptionAnnotationsExce > >> > ption.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 DuplicateOptionAnnotationsExce > >> > ption.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(p > >> ositionalParametersFields); > >> > > + > >> > > + 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).isAnnotationP > >> resent(Option.class)) > >> > { > >> > > + throw MissingParameterException.crea > >> te(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.is > >> Empty()) > >> > { > >> > > + 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 && !v > >> > > > >> > > <TRUNCATED> > >> > > > >> > > >> > >> > >> > >> -- > >> Matt Sicker <boa...@gmail.com> > >> > > > > >
