SubCommandArgumentParser.java revision 99faa045b6241c1d2843cce1b7a9d9c97055beae
0N/A * The contents of this file are subject to the terms of the 0N/A * Common Development and Distribution License, Version 1.0 only 0N/A * (the "License"). You may not use this file except in compliance 2362N/A * You can obtain a copy of the license at 0N/A * See the License for the specific language governing permissions 0N/A * and limitations under the License. 0N/A * When distributing Covered Code, include this CDDL HEADER in each 0N/A * file and include the License file at 0N/A * add the following below this CDDL HEADER, with the fields enclosed 0N/A * by brackets "[]" replaced with your own identifying information: 0N/A * Portions Copyright [yyyy] [name of copyright owner] 0N/A * Portions Copyright 2006-2007 Sun Microsystems, Inc. 0N/A * This class defines a variant of the argument parser that can be used with 0N/A * applications that use subcommands to customize their behavior and that have a 0N/A * different set of options per subcommand (e.g, "cvs checkout" takes different 0N/A * options than "cvs commit"). This parser also has the ability to use global 0N/A * options that will always be applicable regardless of the subcommand in 0N/A * addition to the subcommand-specific arguments. There must not be any 0N/A * conflicts between the global options and the option for any subcommand, but 0N/A * it is allowed to re-use subcommand-specific options for different purposes 0N/A * between different subcommands. 0N/A // The argument that will be used to trigger the display of usage information. 0N/A // Indicates whether subcommand and long argument names should be treated in a 0N/A // case-sensitive manner. 0N/A // Indicates whether the usage information has been displayed. 0N/A // The set of global arguments defined for this parser, referenced by short 0N/A // The set of global arguments defined for this parser, referenced by 0N/A // The set of global arguments defined for this parser, referenced by long 0N/A // The set of subcommands defined for this parser, referenced by subcommand 0N/A // The total set of global arguments defined for this parser. 0N/A // The output stream to which usage information should be printed. 0N/A // The fully-qualified name of the Java class that should be invoked to launch 0N/A // the program with which this argument parser is associated. 0N/A // A human-readable description for the tool, which will be included when 0N/A // displaying usage information. 0N/A // The raw set of command-line arguments that were provided. 0N/A // The subcommand requested by the user as part of the command-line arguments. 0N/A * Creates a new instance of this subcommand argument parser with no 0N/A * @param mainClassName The fully-qualified name of the Java 0N/A * class that should be invoked to launch 0N/A * the program with which this argument 0N/A * parser is associated. 0N/A * @param toolDescription A human-readable description for the 0N/A * tool, which will be included when 0N/A * displaying usage information. 0N/A * @param longArgumentsCaseSensitive Indicates whether subcommand and long 0N/A * argument names should be treated in a 0N/A * case-sensitive manner. 0N/A * Retrieves the fully-qualified name of the Java class that should be invoked 0N/A * to launch the program with which this argument parser is associated. 0N/A * @return The fully-qualified name of the Java class that should be invoked 0N/A * to launch the program with which this argument parser is 0N/A * Retrieves a human-readable description for this tool, which should be 0N/A * included at the top of the command-line usage information. 0N/A * @return A human-readable description for this tool, or {@code null} if 0N/A * none is available. 993N/A * Indicates whether subcommand names and long argument strings should be 0N/A * treated in a case-sensitive manner. 0N/A * @return <CODE>true</CODE> if subcommand names and long argument strings 0N/A * should be treated in a case-sensitive manner, or 0N/A * <CODE>false</CODE> if they should not. 0N/A * Retrieves the list of all global arguments that have been defined for this 0N/A * @return The list of all global arguments that have been defined for this 0N/A * Indicates whether this argument parser contains a global argument with the 0N/A * @param argumentName The name for which to make the determination. 0N/A * @return <CODE>true</CODE> if a global argument exists with the specified 0N/A * name, or <CODE>false</CODE> if not. 0N/A * Retrieves the global argument with the specified name. 0N/A * @param name The name of the global argument to retrieve. 993N/A * @return The global argument with the specified name, or <CODE>null</CODE> 0N/A * if there is no such argument. 0N/A * Retrieves the set of global arguments mapped by the short identifier that 0N/A * may be used to reference them. Note that arguments that do not have a 0N/A * short identifier will not be present in this list. 0N/A * @return The set of global arguments mapped by the short identifier that 0N/A * may be used to reference them. 0N/A * Indicates whether this argument parser has a global argument with the 0N/A * specified short ID. 0N/A * @param shortID The short ID character for which to make the 0N/A * @return <CODE>true</CODE> if a global argument exists with the specified 0N/A * short ID, or <CODE>false</CODE> if not. 0N/A * Retrieves the global argument with the specified short identifier. 0N/A * @param shortID The short identifier for the global argument to retrieve. 0N/A * @return The global argument with the specified short identifier, or 0N/A * <CODE>null</CODE> if there is no such argument. 0N/A * Retrieves the set of global arguments mapped by the long identifier that 0N/A * may be used to reference them. Note that arguments that do not have a long 0N/A * identifier will not be present in this list. 0N/A * @return The set of global arguments mapped by the long identifier that may 0N/A * be used to reference them. 0N/A * Indicates whether this argument parser has a global argument with the 0N/A * specified long ID. 0N/A * @param longID The long ID string for which to make the determination. 0N/A * @return <CODE>true</CODE> if a global argument exists with the specified 0N/A * long ID, or <CODE>false</CODE> if not. * Retrieves the global argument with the specified long identifier. * @param longID The long identifier for the global argument to retrieve. * @return The global argument with the specified long identifier, or * <CODE>null</CODE> if there is no such argument. * Retrieves the set of subcommands defined for this argument parser, * referenced by subcommand name. * @return The set of subcommands defined for this argument parser, * referenced by subcommand name. * Indicates whether this argument parser has a subcommand with the specified * @param name The subcommand name for which to make the determination. * @return <CODE>true</CODE> if this argument parser has a subcommand with * the specified name, or <CODE>false</CODE> if it does not. * Retrieves the subcommand with the specified name. * @param name The name of the subcommand to retrieve. * @return The subcommand with the specified name, or <CODE>null</CODE> if no * such subcommand is defined. * Retrieves the subcommand that was selected in the set of command-line * @return The subcommand that was selected in the set of command-line * arguments, or <CODE>null</CODE> if none was selected. * Retrieves the raw set of arguments that were provided. * @return The raw set of arguments that were provided, or <CODE>null</CODE> * if the argument list has not yet been parsed. * Adds the provided argument to the set of global arguments handled by this * @param argument The argument to be added. * @throws ArgumentException If the provided argument conflicts with another * global or subcommand argument that has already * Sets the provided argument as one which will automatically trigger the * output of usage information if it is provided on the command line and no * further argument validation will be performed. Note that the caller will * still need to add this argument to the parser with the * <CODE>addArgument</CODE> method, and the argument should not be required * and should not take a value. Also, the caller will still need to check * for the presence of the usage argument after calling * <CODE>parseArguments</CODE> to know that no further processing will be * @param argument The argument whose presence should automatically * trigger the display of usage information. * Sets the provided argument as one which will automatically trigger the * output of usage information if it is provided on the command line and no * further argument validation will be performed. Note that the caller will * still need to add this argument to the parser with the * <CODE>addArgument</CODE> method, and the argument should not be required * and should not take a value. Also, the caller will still need to check * for the presence of the usage argument after calling * <CODE>parseArguments</CODE> to know that no further processing will be * @param argument The argument whose presence should automatically * trigger the display of usage information. * @param outputStream The output stream to which the usage information * Adds the provided subcommand to this argument parser. This is only * intended for use by the <CODE>SubCommand</CODE> constructor and does not * do any validation of its own to ensure that there are no conflicts with the * subcommand or any of its arguments. * @param subCommand The subcommand to add to this argument parser. * Parses the provided set of arguments and updates the information associated * with this parser accordingly. * @param rawArguments The raw set of arguments to parse. * @throws ArgumentException If a problem was encountered while parsing the * Parses the provided set of arguments and updates the information associated * with this parser accordingly. Default values for unspecified arguments * may be read from the specified properties file. * @param rawArguments The set of raw arguments to parse. * @param propertiesFile The path to the properties file to use to * obtain default values for unspecified * @param requirePropertiesFile Indicates whether the parsing should fail if * the provided properties file does not exist * @throws ArgumentException If a problem was encountered while parsing the * provided arguments or interacting with the * Parses the provided set of arguments and updates the information associated * with this parser accordingly. Default values for unspecified arguments may * be read from the specified properties if any are provided. * @param rawArguments The set of raw arguments to parse. * @param argumentProperties A set of properties that may be used to provide * default values for arguments not included in * the given raw arguments. * @throws ArgumentException If a problem was encountered while parsing the // This is not legal because we don't allow unnamed trailing arguments // This indicates that we are using the long name to reference the // argument. It may be in any of the following forms: // This is fine. The value is not part of the argument name token. // The argument starts with "--=", which is not acceptable. // The argument is in the form --name=value, so parse them both out. // If we're not case-sensitive, then convert the name to lowercase. // See if the specified name references a global argument. If not, then // see if it references a subcommand argument. // "--help" will always be interpreted as requesting usage // There is no such global argument. // "--help" will always be interpreted as requesting usage // There is no such global or subcommand argument. // If this is the usage argument, then immediately stop and print // See if the argument takes a value. If so, then make sure one was // provided. If not, then make sure none was provided. // If the argument already has a value, then make sure it is // acceptable to have more than one. // This indicates that we are using the 1-character name to reference // the argument. It may be in any of the following forms: // Get the argument with the specified short ID. It may be either a // global argument or a subcommand-specific argument. // "-?" will always be interpreted as requesting usage. // There is no such argument registered. // "-?" will always be interpreted as requesting usage. // There is no such argument registered. // If this is the usage argument, then immediately stop and print // See if the argument takes a value. If so, then make sure one was // provided. If not, then make sure none was provided. // If the argument already has a value, then make sure it is // acceptable to have more than one. // If we've gotten here, then it means that we're in a scenario like // "-abc" where "a" is a valid argument that doesn't take a value. // However, this could still be valid if all remaining characters in // the value are also valid argument characters that don't take // This means we're in a scenario like "-abc" where b is a // valid argument that takes a value. We don't support that. // If this is the usage argument, then immediately stop and // print usage information. // It's not a short or long identifier, so check to see if it is a // subcommand name. If not, then it's invalid. If so, then make sure // that it was the only subcommand provided. // Iterate through all the global arguments and make sure that they have // values or a suitable default is available. // See if there is a default value in the properties that can be used. // If there is still no value, then see if the argument defines a // If there is still no value and the argument is required, then that's // Iterate through all the subcommand-specific arguments and make sure that // they have values or a suitable default is available. // See if there is a default value in the properties that can be used. // If there is still no value, then see if the argument defines a // If there is still no value and the argument is required, then * Appends complete usage information to the provided buffer. It will include * information about global options as well as all subcommand-specific * options. The output will be somewhat compressed in that it will not * include any of the descriptions for any of the arguments. * @param buffer The buffer to which the usage information should be buffer.
append(
"The accepted value for global options are:");
* Appends usage information for the specified subcommand to the provided * @param buffer The buffer to which the usage information should be * @param subCommand The subcommand for which to display the usage // If this argument is hidden, then skip it. // Write a line with the short and/or long identifiers that may be used * Retrieves a string containing usage information based on the defined * @return A string containing usage information based on the defined * Writes usage information based on the defined arguments to the provided * @param outputStream The output stream to which the usage information * @throws IOException If a problem occurs while attempting to write the * usage information to the provided output stream. * Indicates whether the usage information has been displayed to the end user * either by an explicit argument like "-H" or "--help", or by a built-in * @return {@code true} if the usage information has been displayed, or * Write one or more lines with the description of the argument. We will * indent the description five characters and try our best to wrap at or * before column 79 so it will be friendly to 80-column displays. // There are no spaces in the first actualSize -1 columns. See // if there is one after that point. If so, then break there. // If not, then don't break at all.