Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
/*
* Copyright 2008-2022 Ping Identity Corporation
* All Rights Reserved.
*/
/*
* Copyright 2008-2022 Ping Identity Corporation
*
* Licensed 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.
*/
/*
* Copyright (C) 2008-2022 Ping Identity Corporation
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License (GPLv2 only)
* or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see .
*/
package com.unboundid.util.args;
import java.io.BufferedReader;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.PrintStream;
import java.io.PrintWriter;
import java.io.Serializable;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.atomic.AtomicBoolean;
import com.unboundid.ldap.sdk.unboundidds.tools.ToolUtils;
import com.unboundid.util.CommandLineTool;
import com.unboundid.util.Debug;
import com.unboundid.util.NotNull;
import com.unboundid.util.Nullable;
import com.unboundid.util.ObjectPair;
import com.unboundid.util.StaticUtils;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.Validator;
import static com.unboundid.util.args.ArgsMessages.*;
/**
* This class provides an argument parser, which may be used to process command
* line arguments provided to Java applications. See the package-level Javadoc
* documentation for details regarding the capabilities of the argument parser.
*/
@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
public final class ArgumentParser
implements Serializable
{
/**
* The name of the system property that can be used to specify the default
* properties file that should be used to obtain the default values for
* arguments not specified via the command line.
*/
@NotNull public static final String PROPERTY_DEFAULT_PROPERTIES_FILE_PATH =
ArgumentParser.class.getName() + ".propertiesFilePath";
/**
* The name of an environment variable that can be used to specify the default
* properties file that should be used to obtain the default values for
* arguments not specified via the command line.
*/
@NotNull public static final String ENV_DEFAULT_PROPERTIES_FILE_PATH =
"UNBOUNDID_TOOL_PROPERTIES_FILE_PATH";
/**
* The name of the argument used to specify the path to a file to which all
* output should be written.
*/
@NotNull private static final String ARG_NAME_OUTPUT_FILE = "outputFile";
/**
* The name of the argument used to indicate that output should be written to
* both the output file and the console.
*/
@NotNull private static final String ARG_NAME_TEE_OUTPUT = "teeOutput";
/**
* The name of the argument used to specify the path to a properties file from
* which to obtain the default values for arguments not specified via the
* command line.
*/
@NotNull private static final String ARG_NAME_PROPERTIES_FILE_PATH =
"propertiesFilePath";
/**
* The name of the argument used to specify the path to a file to be generated
* with information about the properties that the tool supports.
*/
@NotNull private static final String ARG_NAME_GENERATE_PROPERTIES_FILE =
"generatePropertiesFile";
/**
* The name of the argument used to indicate that the tool should not use any
* properties file to obtain default values for arguments not specified via
* the command line.
*/
@NotNull private static final String ARG_NAME_NO_PROPERTIES_FILE =
"noPropertiesFile";
/**
* The name of the argument used to indicate that the tool should suppress the
* comment that lists the argument values obtained from a properties file.
*/
@NotNull private static final String
ARG_NAME_SUPPRESS_PROPERTIES_FILE_COMMENT =
"suppressPropertiesFileComment";
/**
* The serial version UID for this serializable class.
*/
private static final long serialVersionUID = 3053102992180360269L;
// The command-line tool with which this argument parser is associated, if
// any.
@Nullable private volatile CommandLineTool commandLineTool;
// The properties file used to obtain arguments for this tool.
@Nullable private volatile File propertiesFileUsed;
// The maximum number of trailing arguments allowed to be provided.
private final int maxTrailingArgs;
// The minimum number of trailing arguments allowed to be provided.
private final int minTrailingArgs;
// The set of named arguments associated with this parser, indexed by short
// identifier.
@NotNull private final LinkedHashMap namedArgsByShortID;
// The set of named arguments associated with this parser, indexed by long
// identifier.
@NotNull private final LinkedHashMap namedArgsByLongID;
// The set of subcommands associated with this parser, indexed by name.
@NotNull private final LinkedHashMap subCommandsByName;
// The full set of named arguments associated with this parser.
@NotNull private final List namedArgs;
// Sets of arguments in which if the key argument is provided, then at least
// one of the value arguments must also be provided.
@NotNull private final List>>
dependentArgumentSets;
// Sets of arguments in which at most one argument in the list is allowed to
// be present.
@NotNull private final List> exclusiveArgumentSets;
// Sets of arguments in which at least one argument in the list is required to
// be present.
@NotNull private final List> requiredArgumentSets;
// A list of any arguments set from the properties file rather than explicitly
// provided on the command line.
@NotNull private final List argumentsSetFromPropertiesFile;
// The list of trailing arguments provided on the command line.
@NotNull private final List trailingArgs;
// The full list of subcommands associated with this argument parser.
@NotNull private final List subCommands;
// A list of additional paragraphs that make up the complete description for
// the associated command.
@NotNull private final List additionalCommandDescriptionParagraphs;
// The description for the associated command.
@NotNull private final String commandDescription;
// The name for the associated command.
@NotNull private final String commandName;
// The placeholder string for the trailing arguments.
@Nullable private final String trailingArgsPlaceholder;
// The subcommand with which this argument parser is associated.
@Nullable private volatile SubCommand parentSubCommand;
// The subcommand that was included in the set of command-line arguments.
@Nullable private volatile SubCommand selectedSubCommand;
/**
* Creates a new instance of this argument parser with the provided
* information. It will not allow unnamed trailing arguments.
*
* @param commandName The name of the application or utility with
* which this argument parser is associated. It
* must not be {@code null}.
* @param commandDescription A description of the application or utility
* with which this argument parser is associated.
* It will be included in generated usage
* information. It must not be {@code null}.
*
* @throws ArgumentException If either the command name or command
* description is {@code null},
*/
public ArgumentParser(@NotNull final String commandName,
@NotNull final String commandDescription)
throws ArgumentException
{
this(commandName, commandDescription, 0, null);
}
/**
* Creates a new instance of this argument parser with the provided
* information.
*
* @param commandName The name of the application or utility
* with which this argument parser is
* associated. It must not be {@code null}.
* @param commandDescription A description of the application or
* utility with which this argument parser is
* associated. It will be included in
* generated usage information. It must not
* be {@code null}.
* @param maxTrailingArgs The maximum number of trailing arguments
* that may be provided to this command. A
* value of zero indicates that no trailing
* arguments will be allowed. A value less
* than zero will indicate that there is no
* limit on the number of trailing arguments
* allowed.
* @param trailingArgsPlaceholder A placeholder string that will be included
* in usage output to indicate what trailing
* arguments may be provided. It must not be
* {@code null} if {@code maxTrailingArgs} is
* anything other than zero.
*
* @throws ArgumentException If either the command name or command
* description is {@code null}, or if the maximum
* number of trailing arguments is non-zero and
* the trailing arguments placeholder is
* {@code null}.
*/
public ArgumentParser(@NotNull final String commandName,
@NotNull final String commandDescription,
final int maxTrailingArgs,
@Nullable final String trailingArgsPlaceholder)
throws ArgumentException
{
this(commandName, commandDescription, 0, maxTrailingArgs,
trailingArgsPlaceholder);
}
/**
* Creates a new instance of this argument parser with the provided
* information.
*
* @param commandName The name of the application or utility
* with which this argument parser is
* associated. It must not be {@code null}.
* @param commandDescription A description of the application or
* utility with which this argument parser is
* associated. It will be included in
* generated usage information. It must not
* be {@code null}.
* @param minTrailingArgs The minimum number of trailing arguments
* that must be provided for this command. A
* value of zero indicates that the command
* may be invoked without any trailing
* arguments.
* @param maxTrailingArgs The maximum number of trailing arguments
* that may be provided to this command. A
* value of zero indicates that no trailing
* arguments will be allowed. A value less
* than zero will indicate that there is no
* limit on the number of trailing arguments
* allowed.
* @param trailingArgsPlaceholder A placeholder string that will be included
* in usage output to indicate what trailing
* arguments may be provided. It must not be
* {@code null} if {@code maxTrailingArgs} is
* anything other than zero.
*
* @throws ArgumentException If either the command name or command
* description is {@code null}, or if the maximum
* number of trailing arguments is non-zero and
* the trailing arguments placeholder is
* {@code null}.
*/
public ArgumentParser(@NotNull final String commandName,
@NotNull final String commandDescription,
final int minTrailingArgs,
final int maxTrailingArgs,
@Nullable final String trailingArgsPlaceholder)
throws ArgumentException
{
this(commandName, commandDescription, null, minTrailingArgs,
maxTrailingArgs, trailingArgsPlaceholder);
}
/**
* Creates a new instance of this argument parser with the provided
* information.
*
* @param commandName
* The name of the application or utility with which this
* argument parser is associated. It must not be {@code null}.
* @param commandDescription
* A description of the application or utility with which this
* argument parser is associated. It will be included in
* generated usage information. It must not be {@code null}.
* @param additionalCommandDescriptionParagraphs
* A list of additional paragraphs that should be included in the
* tool description (with {@code commandDescription} providing
* the text for the first paragraph). This may be {@code null}
* or empty if the tool description should only include a
* single paragraph.
* @param minTrailingArgs
* The minimum number of trailing arguments that must be provided
* for this command. A value of zero indicates that the command
* may be invoked without any trailing arguments.
* @param maxTrailingArgs
* The maximum number of trailing arguments that may be provided
* to this command. A value of zero indicates that no trailing
* arguments will be allowed. A value less than zero will
* indicate that there is no limit on the number of trailing
* arguments allowed.
* @param trailingArgsPlaceholder
* A placeholder string that will be included in usage output to
* indicate what trailing arguments may be provided. It must not
* be {@code null} if {@code maxTrailingArgs} is anything other
* than zero.
*
* @throws ArgumentException If either the command name or command
* description is {@code null}, or if the maximum
* number of trailing arguments is non-zero and
* the trailing arguments placeholder is
* {@code null}.
*/
public ArgumentParser(@NotNull final String commandName,
@NotNull final String commandDescription,
@Nullable final List additionalCommandDescriptionParagraphs,
final int minTrailingArgs, final int maxTrailingArgs,
@Nullable final String trailingArgsPlaceholder)
throws ArgumentException
{
if (commandName == null)
{
throw new ArgumentException(ERR_PARSER_COMMAND_NAME_NULL.get());
}
if (commandDescription == null)
{
throw new ArgumentException(ERR_PARSER_COMMAND_DESCRIPTION_NULL.get());
}
if ((maxTrailingArgs != 0) && (trailingArgsPlaceholder == null))
{
throw new ArgumentException(
ERR_PARSER_TRAILING_ARGS_PLACEHOLDER_NULL.get());
}
this.commandName = commandName;
this.commandDescription = commandDescription;
this.trailingArgsPlaceholder = trailingArgsPlaceholder;
if (additionalCommandDescriptionParagraphs == null)
{
this.additionalCommandDescriptionParagraphs = Collections.emptyList();
}
else
{
this.additionalCommandDescriptionParagraphs =
Collections.unmodifiableList(
new ArrayList<>(additionalCommandDescriptionParagraphs));
}
if (minTrailingArgs >= 0)
{
this.minTrailingArgs = minTrailingArgs;
}
else
{
this.minTrailingArgs = 0;
}
if (maxTrailingArgs >= 0)
{
this.maxTrailingArgs = maxTrailingArgs;
}
else
{
this.maxTrailingArgs = Integer.MAX_VALUE;
}
if (this.minTrailingArgs > this.maxTrailingArgs)
{
throw new ArgumentException(ERR_PARSER_TRAILING_ARGS_COUNT_MISMATCH.get(
this.minTrailingArgs, this.maxTrailingArgs));
}
namedArgsByShortID =
new LinkedHashMap<>(StaticUtils.computeMapCapacity(20));
namedArgsByLongID = new LinkedHashMap<>(StaticUtils.computeMapCapacity(20));
namedArgs = new ArrayList<>(20);
trailingArgs = new ArrayList<>(20);
dependentArgumentSets = new ArrayList<>(20);
exclusiveArgumentSets = new ArrayList<>(20);
requiredArgumentSets = new ArrayList<>(20);
parentSubCommand = null;
selectedSubCommand = null;
subCommands = new ArrayList<>(20);
subCommandsByName = new LinkedHashMap<>(StaticUtils.computeMapCapacity(20));
propertiesFileUsed = null;
argumentsSetFromPropertiesFile = new ArrayList<>(20);
commandLineTool = null;
}
/**
* Creates a new argument parser that is a "clean" copy of the provided source
* argument parser.
*
* @param source The source argument parser to use for this argument
* parser.
* @param subCommand The subcommand with which this argument parser is to be
* associated.
*/
ArgumentParser(@NotNull final ArgumentParser source,
@Nullable final SubCommand subCommand)
{
commandName = source.commandName;
commandDescription = source.commandDescription;
minTrailingArgs = source.minTrailingArgs;
maxTrailingArgs = source.maxTrailingArgs;
trailingArgsPlaceholder = source.trailingArgsPlaceholder;
additionalCommandDescriptionParagraphs =
source.additionalCommandDescriptionParagraphs;
propertiesFileUsed = null;
argumentsSetFromPropertiesFile = new ArrayList<>(20);
trailingArgs = new ArrayList<>(20);
namedArgs = new ArrayList<>(source.namedArgs.size());
namedArgsByLongID = new LinkedHashMap<>(
StaticUtils.computeMapCapacity(source.namedArgsByLongID.size()));
namedArgsByShortID = new LinkedHashMap<>(
StaticUtils.computeMapCapacity(source.namedArgsByShortID.size()));
final LinkedHashMap argsByID = new LinkedHashMap<>(
StaticUtils.computeMapCapacity(source.namedArgs.size()));
for (final Argument sourceArg : source.namedArgs)
{
final Argument a = sourceArg.getCleanCopy();
try
{
a.setRegistered();
}
catch (final ArgumentException ae)
{
// This should never happen.
Debug.debugException(ae);
}
namedArgs.add(a);
argsByID.put(a.getIdentifierString(), a);
for (final Character c : a.getShortIdentifiers(true))
{
namedArgsByShortID.put(c, a);
}
for (final String s : a.getLongIdentifiers(true))
{
namedArgsByLongID.put(StaticUtils.toLowerCase(s), a);
}
}
dependentArgumentSets =
new ArrayList<>(source.dependentArgumentSets.size());
for (final ObjectPair> p :
source.dependentArgumentSets)
{
final Set sourceSet = p.getSecond();
final LinkedHashSet newSet = new LinkedHashSet<>(
StaticUtils.computeMapCapacity(sourceSet.size()));
for (final Argument a : sourceSet)
{
newSet.add(argsByID.get(a.getIdentifierString()));
}
final Argument sourceFirst = p.getFirst();
final Argument newFirst = argsByID.get(sourceFirst.getIdentifierString());
dependentArgumentSets.add(
new ObjectPair>(newFirst, newSet));
}
exclusiveArgumentSets =
new ArrayList<>(source.exclusiveArgumentSets.size());
for (final Set sourceSet : source.exclusiveArgumentSets)
{
final LinkedHashSet newSet = new LinkedHashSet<>(
StaticUtils.computeMapCapacity(sourceSet.size()));
for (final Argument a : sourceSet)
{
newSet.add(argsByID.get(a.getIdentifierString()));
}
exclusiveArgumentSets.add(newSet);
}
requiredArgumentSets =
new ArrayList<>(source.requiredArgumentSets.size());
for (final Set sourceSet : source.requiredArgumentSets)
{
final LinkedHashSet newSet = new LinkedHashSet<>(
StaticUtils.computeMapCapacity(sourceSet.size()));
for (final Argument a : sourceSet)
{
newSet.add(argsByID.get(a.getIdentifierString()));
}
requiredArgumentSets.add(newSet);
}
parentSubCommand = subCommand;
selectedSubCommand = null;
subCommands = new ArrayList<>(source.subCommands.size());
subCommandsByName = new LinkedHashMap<>(
StaticUtils.computeMapCapacity(source.subCommandsByName.size()));
for (final SubCommand sc : source.subCommands)
{
subCommands.add(sc.getCleanCopy());
for (final String name : sc.getNames(true))
{
subCommandsByName.put(StaticUtils.toLowerCase(name), sc);
}
}
}
/**
* Retrieves the name of the application or utility with which this command
* line argument parser is associated.
*
* @return The name of the application or utility with which this command
* line argument parser is associated.
*/
@NotNull()
public String getCommandName()
{
return commandName;
}
/**
* Retrieves a description of the application or utility with which this
* command line argument parser is associated. If the description should
* include multiple paragraphs, then this method will return the text for the
* first paragraph, and the
* {@link #getAdditionalCommandDescriptionParagraphs()} method should return a
* list with the text for all subsequent paragraphs.
*
* @return A description of the application or utility with which this
* command line argument parser is associated.
*/
@NotNull()
public String getCommandDescription()
{
return commandDescription;
}
/**
* Retrieves a list containing the the text for all subsequent paragraphs to
* include in the description for the application or utility with which this
* command line argument parser is associated. If the description should have
* multiple paragraphs, then the {@link #getCommandDescription()} method will
* provide the text for the first paragraph and this method will provide the
* text for the subsequent paragraphs. If the description should only have a
* single paragraph, then the text of that paragraph should be returned by the
* {@code getCommandDescription} method, and this method will return an empty
* list.
*
* @return A list containing the text for all subsequent paragraphs to
* include in the description for the application or utility with
* which this command line argument parser is associated, or an empty
* list if the description should only include a single paragraph.
*/
@NotNull()
public List getAdditionalCommandDescriptionParagraphs()
{
return additionalCommandDescriptionParagraphs;
}
/**
* Indicates whether this argument parser allows any unnamed trailing
* arguments to be provided.
*
* @return {@code true} if at least one unnamed trailing argument may be
* provided, or {@code false} if not.
*/
public boolean allowsTrailingArguments()
{
return (maxTrailingArgs != 0);
}
/**
* Indicates whether this argument parser requires at least unnamed trailing
* argument to be provided.
*
* @return {@code true} if at least one unnamed trailing argument must be
* provided, or {@code false} if the tool may be invoked without any
* such arguments.
*/
public boolean requiresTrailingArguments()
{
return (minTrailingArgs != 0);
}
/**
* Retrieves the placeholder string that will be provided in usage information
* to indicate what may be included in the trailing arguments.
*
* @return The placeholder string that will be provided in usage information
* to indicate what may be included in the trailing arguments, or
* {@code null} if unnamed trailing arguments are not allowed.
*/
@Nullable()
public String getTrailingArgumentsPlaceholder()
{
return trailingArgsPlaceholder;
}
/**
* Retrieves the minimum number of unnamed trailing arguments that must be
* provided.
*
* @return The minimum number of unnamed trailing arguments that must be
* provided.
*/
public int getMinTrailingArguments()
{
return minTrailingArgs;
}
/**
* Retrieves the maximum number of unnamed trailing arguments that may be
* provided.
*
* @return The maximum number of unnamed trailing arguments that may be
* provided.
*/
public int getMaxTrailingArguments()
{
return maxTrailingArgs;
}
/**
* Updates this argument parser to enable support for a properties file that
* can be used to specify the default values for any properties that were not
* supplied via the command line. This method should be invoked after the
* argument parser has been configured with all of the other arguments that it
* supports and before the {@link #parse} method is invoked. In addition,
* after invoking the {@code parse} method, the caller must also invoke the
* {@link #getGeneratedPropertiesFile} method to determine if the only
* processing performed that should be performed is the generation of a
* properties file that will have already been performed.
*
* This method will update the argument parser to add the following additional
* arguments:
*
*
* {@code propertiesFilePath} -- Specifies the path to the properties file
* that should be used to obtain default values for any arguments not
* provided on the command line. If this is not specified and the
* {@code noPropertiesFile} argument is not present, then the argument
* parser may use a default properties file path specified using either
* the {@code com.unboundid.util.args.ArgumentParser.propertiesFilePath}
* system property or the {@code UNBOUNDID_TOOL_PROPERTIES_FILE_PATH}
* environment variable.
*
*
* {@code generatePropertiesFile} -- Indicates that the tool should
* generate a properties file for this argument parser and write it to the
* specified location. The generated properties file will not have any
* properties set, but will include comments that describe all of the
* supported arguments, as well general information about the use of a
* properties file. If this argument is specified on the command line,
* then no other arguments should be given.
*
*
* {@code noPropertiesFile} -- Indicates that the tool should not use a
* properties file to obtain default values for any arguments not provided
* on the command line.
*
*
*
* @throws ArgumentException If any of the arguments related to properties
* file processing conflicts with an argument that
* has already been added to the argument parser.
*/
public void enablePropertiesFileSupport()
throws ArgumentException
{
final FileArgument propertiesFilePath = new FileArgument(null,
ARG_NAME_PROPERTIES_FILE_PATH, false, 1, null,
INFO_ARG_DESCRIPTION_PROP_FILE_PATH.get(), true, true, true, false);
propertiesFilePath.setUsageArgument(true);
propertiesFilePath.addLongIdentifier("properties-file-path", true);
addArgument(propertiesFilePath);
final FileArgument generatePropertiesFile = new FileArgument(null,
ARG_NAME_GENERATE_PROPERTIES_FILE, false, 1, null,
INFO_ARG_DESCRIPTION_GEN_PROP_FILE.get(), false, true, true, false);
generatePropertiesFile.setUsageArgument(true);
generatePropertiesFile.addLongIdentifier("generate-properties-file", true);
addArgument(generatePropertiesFile);
final BooleanArgument noPropertiesFile = new BooleanArgument(null,
ARG_NAME_NO_PROPERTIES_FILE, INFO_ARG_DESCRIPTION_NO_PROP_FILE.get());
noPropertiesFile.setUsageArgument(true);
noPropertiesFile.addLongIdentifier("no-properties-file", true);
addArgument(noPropertiesFile);
final BooleanArgument suppressPropertiesFileComment = new BooleanArgument(
null, ARG_NAME_SUPPRESS_PROPERTIES_FILE_COMMENT, 1,
INFO_ARG_DESCRIPTION_SUPPRESS_PROP_FILE_COMMENT.get());
suppressPropertiesFileComment.setUsageArgument(true);
suppressPropertiesFileComment.addLongIdentifier(
"suppress-properties-file-comment", true);
addArgument(suppressPropertiesFileComment);
// The propertiesFilePath and noPropertiesFile arguments cannot be used
// together.
addExclusiveArgumentSet(propertiesFilePath, noPropertiesFile);
}
/**
* Indicates whether this argument parser was used to generate a properties
* file. If so, then the tool invoking the parser should return without
* performing any further processing.
*
* @return A {@code File} object that represents the path to the properties
* file that was generated, or {@code null} if no properties file was
* generated.
*/
@Nullable()
public File getGeneratedPropertiesFile()
{
final Argument a = getNamedArgument(ARG_NAME_GENERATE_PROPERTIES_FILE);
if ((a == null) || (! a.isPresent()) || (! (a instanceof FileArgument)))
{
return null;
}
return ((FileArgument) a).getValue();
}
/**
* Retrieves the named argument with the specified short identifier.
*
* @param shortIdentifier The short identifier of the argument to retrieve.
* It must not be {@code null}.
*
* @return The named argument with the specified short identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public Argument getNamedArgument(@NotNull final Character shortIdentifier)
{
Validator.ensureNotNull(shortIdentifier);
return namedArgsByShortID.get(shortIdentifier);
}
/**
* Retrieves the named argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The named argument with the specified long identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public Argument getNamedArgument(@NotNull final String identifier)
{
Validator.ensureNotNull(identifier);
if (identifier.startsWith("--") && (identifier.length() > 2))
{
return namedArgsByLongID.get(
StaticUtils.toLowerCase(identifier.substring(2)));
}
else if (identifier.startsWith("-") && (identifier.length() == 2))
{
return namedArgsByShortID.get(identifier.charAt(1));
}
else
{
return namedArgsByLongID.get(StaticUtils.toLowerCase(identifier));
}
}
/**
* Retrieves the argument list argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The argument list argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public ArgumentListArgument getArgumentListArgument(
@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (ArgumentListArgument) a;
}
}
/**
* Retrieves the Boolean argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The Boolean argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public BooleanArgument getBooleanArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (BooleanArgument) a;
}
}
/**
* Retrieves the Boolean value argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The Boolean value argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public BooleanValueArgument getBooleanValueArgument(
@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (BooleanValueArgument) a;
}
}
/**
* Retrieves the control argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The control argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public ControlArgument getControlArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (ControlArgument) a;
}
}
/**
* Retrieves the DN argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The DN argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public DNArgument getDNArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (DNArgument) a;
}
}
/**
* Retrieves the duration argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The duration argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public DurationArgument getDurationArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (DurationArgument) a;
}
}
/**
* Retrieves the file argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The file argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public FileArgument getFileArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (FileArgument) a;
}
}
/**
* Retrieves the filter argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The filter argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public FilterArgument getFilterArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (FilterArgument) a;
}
}
/**
* Retrieves the integer argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The integer argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public IntegerArgument getIntegerArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (IntegerArgument) a;
}
}
/**
* Retrieves the scope argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The scope argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public ScopeArgument getScopeArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (ScopeArgument) a;
}
}
/**
* Retrieves the string argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The string argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public StringArgument getStringArgument(@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (StringArgument) a;
}
}
/**
* Retrieves the timestamp argument with the specified identifier.
*
* @param identifier The identifier of the argument to retrieve. It may be
* the long identifier without any dashes, the short
* identifier character preceded by a single dash, or the
* long identifier preceded by two dashes. It must not be
* {@code null}.
*
* @return The timestamp argument with the specified identifier, or
* {@code null} if there is no such argument.
*/
@Nullable()
public TimestampArgument getTimestampArgument(
@NotNull final String identifier)
{
final Argument a = getNamedArgument(identifier);
if (a == null)
{
return null;
}
else
{
return (TimestampArgument) a;
}
}
/**
* Retrieves the set of named arguments defined for use with this argument
* parser.
*
* @return The set of named arguments defined for use with this argument
* parser.
*/
@NotNull()
public List getNamedArguments()
{
return Collections.unmodifiableList(namedArgs);
}
/**
* Registers the provided argument with this argument parser.
*
* @param argument The argument to be registered.
*
* @throws ArgumentException If the provided argument conflicts with another
* argument already registered with this parser.
*/
public void addArgument(@NotNull final Argument argument)
throws ArgumentException
{
argument.setRegistered();
for (final Character c : argument.getShortIdentifiers(true))
{
if (namedArgsByShortID.containsKey(c))
{
throw new ArgumentException(ERR_PARSER_SHORT_ID_CONFLICT.get(c));
}
if ((parentSubCommand != null) &&
(parentSubCommand.getArgumentParser().namedArgsByShortID.containsKey(
c)))
{
throw new ArgumentException(ERR_PARSER_SHORT_ID_CONFLICT.get(c));
}
}
for (final String s : argument.getLongIdentifiers(true))
{
if (namedArgsByLongID.containsKey(StaticUtils.toLowerCase(s)))
{
throw new ArgumentException(ERR_PARSER_LONG_ID_CONFLICT.get(s));
}
if ((parentSubCommand != null) &&
(parentSubCommand.getArgumentParser().namedArgsByLongID.containsKey(
StaticUtils.toLowerCase(s))))
{
throw new ArgumentException(ERR_PARSER_LONG_ID_CONFLICT.get(s));
}
}
for (final SubCommand sc : subCommands)
{
final ArgumentParser parser = sc.getArgumentParser();
for (final Character c : argument.getShortIdentifiers(true))
{
if (parser.namedArgsByShortID.containsKey(c))
{
throw new ArgumentException(
ERR_PARSER_SHORT_ID_CONFLICT_WITH_SUBCOMMAND.get(c,
sc.getPrimaryName()));
}
}
for (final String s : argument.getLongIdentifiers(true))
{
if (parser.namedArgsByLongID.containsKey(StaticUtils.toLowerCase(s)))
{
throw new ArgumentException(
ERR_PARSER_LONG_ID_CONFLICT_WITH_SUBCOMMAND.get(s,
sc.getPrimaryName()));
}
}
}
for (final Character c : argument.getShortIdentifiers(true))
{
namedArgsByShortID.put(c, argument);
}
for (final String s : argument.getLongIdentifiers(true))
{
namedArgsByLongID.put(StaticUtils.toLowerCase(s), argument);
}
namedArgs.add(argument);
}
/**
* Retrieves the list of dependent argument sets for this argument parser. If
* an argument contained as the first object in the pair in a dependent
* argument set is provided, then at least one of the arguments in the paired
* set must also be provided.
*
* @return The list of dependent argument sets for this argument parser.
*/
@NotNull()
public List>> getDependentArgumentSets()
{
return Collections.unmodifiableList(dependentArgumentSets);
}
/**
* Adds the provided collection of arguments as dependent upon the given
* argument. All of the arguments must have already been registered with this
* argument parser using the {@link #addArgument} method.
*
* @param targetArgument The argument whose presence indicates that at
* least one of the dependent arguments must also
* be present. It must not be {@code null}, and
* it must have already been registered with this
* argument parser.
* @param dependentArguments The set of arguments from which at least one
* argument must be present if the target argument
* is present. It must not be {@code null} or
* empty, and all arguments must have already been
* registered with this argument parser.
*/
public void addDependentArgumentSet(@NotNull final Argument targetArgument,
@NotNull final Collection dependentArguments)
{
Validator.ensureNotNull(targetArgument, dependentArguments);
Validator.ensureFalse(dependentArguments.isEmpty(),
"The ArgumentParser.addDependentArgumentSet method must not be " +
"called with an empty collection of dependentArguments");
Validator.ensureTrue(namedArgs.contains(targetArgument),
"The ArgumentParser.addDependentArgumentSet method may only be used " +
"if all of the provided arguments have already been registered " +
"with the argument parser via the ArgumentParser.addArgument " +
"method. The " + targetArgument.getIdentifierString() +
" argument has not been registered with the argument parser.");
for (final Argument a : dependentArguments)
{
Validator.ensureTrue(namedArgs.contains(a),
"The ArgumentParser.addDependentArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
a.getIdentifierString() + " argument has not been registered " +
"with the argument parser.");
}
final LinkedHashSet argSet =
new LinkedHashSet<>(dependentArguments);
dependentArgumentSets.add(
new ObjectPair>(targetArgument, argSet));
}
/**
* Adds the provided collection of arguments as dependent upon the given
* argument. All of the arguments must have already been registered with this
* argument parser using the {@link #addArgument} method.
*
* @param targetArgument The argument whose presence indicates that at least
* one of the dependent arguments must also be
* present. It must not be {@code null}, and it must
* have already been registered with this argument
* parser.
* @param dependentArg1 The first argument in the set of arguments in which
* at least one argument must be present if the target
* argument is present. It must not be {@code null},
* and it must have already been registered with this
* argument parser.
* @param remaining The remaining arguments in the set of arguments in
* which at least one argument must be present if the
* target argument is present. It may be {@code null}
* or empty if no additional dependent arguments are
* needed, but if it is non-empty then all arguments
* must have already been registered with this
* argument parser.
*/
public void addDependentArgumentSet(@NotNull final Argument targetArgument,
@NotNull final Argument dependentArg1,
@Nullable final Argument... remaining)
{
Validator.ensureNotNull(targetArgument, dependentArg1);
Validator.ensureTrue(namedArgs.contains(targetArgument),
"The ArgumentParser.addDependentArgumentSet method may only be used " +
"if all of the provided arguments have already been registered " +
"with the argument parser via the ArgumentParser.addArgument " +
"method. The " + targetArgument.getIdentifierString() +
" argument has not been registered with the argument parser.");
Validator.ensureTrue(namedArgs.contains(dependentArg1),
"The ArgumentParser.addDependentArgumentSet method may only be used " +
"if all of the provided arguments have already been registered " +
"with the argument parser via the ArgumentParser.addArgument " +
"method. The " + dependentArg1.getIdentifierString() +
" argument has not been registered with the argument parser.");
if (remaining != null)
{
for (final Argument a : remaining)
{
Validator.ensureTrue(namedArgs.contains(a),
"The ArgumentParser.addDependentArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
a.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
}
}
final LinkedHashSet argSet =
new LinkedHashSet<>(StaticUtils.computeMapCapacity(10));
argSet.add(dependentArg1);
if (remaining != null)
{
argSet.addAll(Arrays.asList(remaining));
}
dependentArgumentSets.add(
new ObjectPair>(targetArgument, argSet));
}
/**
* Adds the provided set of arguments as mutually dependent, such that if any
* of the arguments is provided, then all of them must be provided. It will
* be implemented by creating multiple dependent argument sets (one for each
* argument in the provided collection).
*
* @param arguments The collection of arguments to be used to create the
* dependent argument sets. It must not be {@code null},
* and must contain at least two elements.
*/
public void addMutuallyDependentArgumentSet(
@NotNull final Collection arguments)
{
Validator.ensureNotNullWithMessage(arguments,
"ArgumentParser.addMutuallyDependentArgumentSet.arguments must not " +
"be null.");
Validator.ensureTrue((arguments.size() >= 2),
"ArgumentParser.addMutuallyDependentArgumentSet.arguments must " +
"contain at least two elements.");
for (final Argument a : arguments)
{
Validator.ensureTrue(namedArgs.contains(a),
"ArgumentParser.addMutuallyDependentArgumentSet invoked with " +
"argument " + a.getIdentifierString() +
" that is not registered with the argument parser.");
}
final Set allArgsSet = new HashSet<>(arguments);
for (final Argument a : allArgsSet)
{
final Set dependentArgs = new HashSet<>(allArgsSet);
dependentArgs.remove(a);
addDependentArgumentSet(a, dependentArgs);
}
}
/**
* Adds the provided set of arguments as mutually dependent, such that if any
* of the arguments is provided, then all of them must be provided. It will
* be implemented by creating multiple dependent argument sets (one for each
* argument in the provided collection).
*
* @param arg1 The first argument to include in the mutually dependent
* argument set. It must not be {@code null}.
* @param arg2 The second argument to include in the mutually dependent
* argument set. It must not be {@code null}.
* @param remaining An optional set of additional arguments to include in
* the mutually dependent argument set. It may be
* {@code null} or empty if only two arguments should be
* included in the mutually dependent argument set.
*/
public void addMutuallyDependentArgumentSet(@NotNull final Argument arg1,
@NotNull final Argument arg2,
@Nullable final Argument... remaining)
{
Validator.ensureNotNullWithMessage(arg1,
"ArgumentParser.addMutuallyDependentArgumentSet.arg1 must not be " +
"null.");
Validator.ensureNotNullWithMessage(arg2,
"ArgumentParser.addMutuallyDependentArgumentSet.arg2 must not be " +
"null.");
final List args = new ArrayList<>(10);
args.add(arg1);
args.add(arg2);
if (remaining != null)
{
args.addAll(Arrays.asList(remaining));
}
addMutuallyDependentArgumentSet(args);
}
/**
* Retrieves the list of exclusive argument sets for this argument parser.
* If an argument contained in an exclusive argument set is provided, then
* none of the other arguments in that set may be provided. It is acceptable
* for none of the arguments in the set to be provided, unless the same set
* of arguments is also defined as a required argument set.
*
* @return The list of exclusive argument sets for this argument parser.
*/
@NotNull()
public List> getExclusiveArgumentSets()
{
return Collections.unmodifiableList(exclusiveArgumentSets);
}
/**
* Adds the provided collection of arguments as an exclusive argument set, in
* which at most one of the arguments may be provided. All of the arguments
* must have already been registered with this argument parser using the
* {@link #addArgument} method.
*
* @param exclusiveArguments The collection of arguments to form an
* exclusive argument set. It must not be
* {@code null}, and all of the arguments must
* have already been registered with this argument
* parser.
*/
public void addExclusiveArgumentSet(
@NotNull final Collection exclusiveArguments)
{
Validator.ensureNotNull(exclusiveArguments);
for (final Argument a : exclusiveArguments)
{
Validator.ensureTrue(namedArgs.contains(a),
"The ArgumentParser.addExclusiveArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
a.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
}
final LinkedHashSet argSet =
new LinkedHashSet<>(exclusiveArguments);
exclusiveArgumentSets.add(Collections.unmodifiableSet(argSet));
}
/**
* Adds the provided set of arguments as an exclusive argument set, in
* which at most one of the arguments may be provided. All of the arguments
* must have already been registered with this argument parser using the
* {@link #addArgument} method.
*
* @param arg1 The first argument to include in the exclusive argument
* set. It must not be {@code null}, and it must have
* already been registered with this argument parser.
* @param arg2 The second argument to include in the exclusive argument
* set. It must not be {@code null}, and it must have
* already been registered with this argument parser.
* @param remaining Any additional arguments to include in the exclusive
* argument set. It may be {@code null} or empty if no
* additional exclusive arguments are needed, but if it is
* non-empty then all arguments must have already been
* registered with this argument parser.
*/
public void addExclusiveArgumentSet(@NotNull final Argument arg1,
@NotNull final Argument arg2,
@Nullable final Argument... remaining)
{
Validator.ensureNotNull(arg1, arg2);
Validator.ensureTrue(namedArgs.contains(arg1),
"The ArgumentParser.addExclusiveArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
arg1.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
Validator.ensureTrue(namedArgs.contains(arg2),
"The ArgumentParser.addExclusiveArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
arg2.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
if (remaining != null)
{
for (final Argument a : remaining)
{
Validator.ensureTrue(namedArgs.contains(a),
"The ArgumentParser.addExclusiveArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
a.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
}
}
final LinkedHashSet argSet =
new LinkedHashSet<>(StaticUtils.computeMapCapacity(10));
argSet.add(arg1);
argSet.add(arg2);
if (remaining != null)
{
argSet.addAll(Arrays.asList(remaining));
}
exclusiveArgumentSets.add(Collections.unmodifiableSet(argSet));
}
/**
* Retrieves the list of required argument sets for this argument parser. At
* least one of the arguments contained in this set must be provided. If this
* same set is also defined as an exclusive argument set, then exactly one
* of those arguments must be provided.
*
* @return The list of required argument sets for this argument parser.
*/
@NotNull()
public List> getRequiredArgumentSets()
{
return Collections.unmodifiableList(requiredArgumentSets);
}
/**
* Adds the provided collection of arguments as a required argument set, in
* which at least one of the arguments must be provided. All of the arguments
* must have already been registered with this argument parser using the
* {@link #addArgument} method.
*
* @param requiredArguments The collection of arguments to form an
* required argument set. It must not be
* {@code null}, and all of the arguments must have
* already been registered with this argument
* parser.
*/
public void addRequiredArgumentSet(
@NotNull final Collection requiredArguments)
{
Validator.ensureNotNull(requiredArguments);
for (final Argument a : requiredArguments)
{
Validator.ensureTrue(namedArgs.contains(a),
"The ArgumentParser.addRequiredArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
a.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
}
final LinkedHashSet argSet =
new LinkedHashSet<>(requiredArguments);
requiredArgumentSets.add(Collections.unmodifiableSet(argSet));
}
/**
* Adds the provided set of arguments as a required argument set, in which
* at least one of the arguments must be provided. All of the arguments must
* have already been registered with this argument parser using the
* {@link #addArgument} method.
*
* @param arg1 The first argument to include in the required argument
* set. It must not be {@code null}, and it must have
* already been registered with this argument parser.
* @param arg2 The second argument to include in the required argument
* set. It must not be {@code null}, and it must have
* already been registered with this argument parser.
* @param remaining Any additional arguments to include in the required
* argument set. It may be {@code null} or empty if no
* additional required arguments are needed, but if it is
* non-empty then all arguments must have already been
* registered with this argument parser.
*/
public void addRequiredArgumentSet(@NotNull final Argument arg1,
@NotNull final Argument arg2,
@Nullable final Argument... remaining)
{
Validator.ensureNotNull(arg1, arg2);
Validator.ensureTrue(namedArgs.contains(arg1),
"The ArgumentParser.addRequiredArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
arg1.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
Validator.ensureTrue(namedArgs.contains(arg2),
"The ArgumentParser.addRequiredArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
arg2.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
if (remaining != null)
{
for (final Argument a : remaining)
{
Validator.ensureTrue(namedArgs.contains(a),
"The ArgumentParser.addRequiredArgumentSet method may only be " +
"used if all of the provided arguments have already been " +
"registered with the argument parser via the " +
"ArgumentParser.addArgument method. The " +
a.getIdentifierString() + " argument has not been " +
"registered with the argument parser.");
}
}
final LinkedHashSet argSet =
new LinkedHashSet<>(StaticUtils.computeMapCapacity(10));
argSet.add(arg1);
argSet.add(arg2);
if (remaining != null)
{
argSet.addAll(Arrays.asList(remaining));
}
requiredArgumentSets.add(Collections.unmodifiableSet(argSet));
}
/**
* Indicates whether any subcommands have been registered with this argument
* parser.
*
* @return {@code true} if one or more subcommands have been registered with
* this argument parser, or {@code false} if not.
*/
public boolean hasSubCommands()
{
return (! subCommands.isEmpty());
}
/**
* Retrieves the subcommand that was provided in the set of command-line
* arguments, if any.
*
* @return The subcommand that was provided in the set of command-line
* arguments, or {@code null} if there is none.
*/
@Nullable()
public SubCommand getSelectedSubCommand()
{
return selectedSubCommand;
}
/**
* Specifies the subcommand that was provided in the set of command-line
* arguments.
*
* @param subcommand The subcommand that was provided in the set of
* command-line arguments. It may be {@code null} if no
* subcommand should be used.
*/
void setSelectedSubCommand(@Nullable final SubCommand subcommand)
{
selectedSubCommand = subcommand;
if (subcommand != null)
{
subcommand.setPresent();
}
}
/**
* Retrieves a list of all subcommands associated with this argument parser.
*
* @return A list of all subcommands associated with this argument parser, or
* an empty list if there are no associated subcommands.
*/
@NotNull()
public List getSubCommands()
{
return Collections.unmodifiableList(subCommands);
}
/**
* Retrieves the subcommand for the provided name.
*
* @param name The name of the subcommand to retrieve.
*
* @return The subcommand with the provided name, or {@code null} if there is
* no such subcommand.
*/
@Nullable()
public SubCommand getSubCommand(@Nullable final String name)
{
if (name == null)
{
return null;
}
return subCommandsByName.get(StaticUtils.toLowerCase(name));
}
/**
* Registers the provided subcommand with this argument parser.
*
* @param subCommand The subcommand to register with this argument parser.
* It must not be {@code null}.
*
* @throws ArgumentException If this argument parser does not allow
* subcommands, if there is a conflict between any
* of the names of the provided subcommand and an
* already-registered subcommand, or if there is a
* conflict between any of the subcommand-specific
* arguments and global arguments.
*/
public void addSubCommand(@NotNull final SubCommand subCommand)
throws ArgumentException
{
// Ensure that the subcommand isn't already registered with an argument
// parser.
if (subCommand.getGlobalArgumentParser() != null)
{
throw new ArgumentException(
ERR_PARSER_SUBCOMMAND_ALREADY_REGISTERED_WITH_PARSER.get());
}
// Ensure that the caller isn't trying to create a nested subcommand.
if (parentSubCommand != null)
{
throw new ArgumentException(
ERR_PARSER_CANNOT_CREATE_NESTED_SUBCOMMAND.get(
parentSubCommand.getPrimaryName()));
}
// Ensure that this argument parser doesn't allow trailing arguments.
if (allowsTrailingArguments())
{
throw new ArgumentException(
ERR_PARSER_WITH_TRAILING_ARGS_CANNOT_HAVE_SUBCOMMANDS.get());
}
// Ensure that the subcommand doesn't have any names that conflict with an
// existing subcommand.
for (final String name : subCommand.getNames(true))
{
if (subCommandsByName.containsKey(StaticUtils.toLowerCase(name)))
{
throw new ArgumentException(
ERR_SUBCOMMAND_NAME_ALREADY_IN_USE.get(name));
}
}
// Register the subcommand.
for (final String name : subCommand.getNames(true))
{
subCommandsByName.put(StaticUtils.toLowerCase(name), subCommand);
}
subCommands.add(subCommand);
subCommand.setGlobalArgumentParser(this);
}
/**
* Registers the provided additional name for this subcommand.
*
* @param name The name to be registered. It must not be
* {@code null} or empty.
* @param subCommand The subcommand with which the name is associated. It
* must not be {@code null}.
*
* @throws ArgumentException If the provided name is already in use.
*/
void addSubCommand(@NotNull final String name,
@NotNull final SubCommand subCommand)
throws ArgumentException
{
final String lowerName = StaticUtils.toLowerCase(name);
if (subCommandsByName.containsKey(lowerName))
{
throw new ArgumentException(
ERR_SUBCOMMAND_NAME_ALREADY_IN_USE.get(name));
}
subCommandsByName.put(lowerName, subCommand);
}
/**
* Retrieves the set of unnamed trailing arguments in the provided command
* line arguments.
*
* @return The set of unnamed trailing arguments in the provided command line
* arguments, or an empty list if there were none.
*/
@NotNull()
public List getTrailingArguments()
{
return Collections.unmodifiableList(trailingArgs);
}
/**
* Resets this argument parser so that it appears as if it had not been used
* to parse any command-line arguments.
*/
void reset()
{
selectedSubCommand = null;
for (final Argument a : namedArgs)
{
a.reset();
}
propertiesFileUsed = null;
argumentsSetFromPropertiesFile.clear();
trailingArgs.clear();
}
/**
* Clears the set of trailing arguments for this argument parser.
*/
void resetTrailingArguments()
{
trailingArgs.clear();
}
/**
* Adds the provided value to the set of trailing arguments.
*
* @param value The value to add to the set of trailing arguments.
*
* @throws ArgumentException If the parser already has the maximum allowed
* number of trailing arguments.
*/
void addTrailingArgument(@NotNull final String value)
throws ArgumentException
{
if ((maxTrailingArgs > 0) && (trailingArgs.size() >= maxTrailingArgs))
{
throw new ArgumentException(ERR_PARSER_TOO_MANY_TRAILING_ARGS.get(value,
commandName, maxTrailingArgs));
}
trailingArgs.add(value);
}
/**
* Retrieves the properties file that was used to obtain values for arguments
* not set on the command line.
*
* @return The properties file that was used to obtain values for arguments
* not set on the command line, or {@code null} if no properties file
* was used.
*/
@Nullable()
public File getPropertiesFileUsed()
{
return propertiesFileUsed;
}
/**
* Retrieves a list of the string representations of any arguments used for
* the associated tool that were set from a properties file rather than
* provided on the command line. The values of any arguments marked as
* sensitive will be obscured.
*
* @return A list of the string representations any arguments used for the
* associated tool that were set from a properties file rather than
* provided on the command line, or an empty list if no arguments
* were set from a properties file.
*/
@NotNull()
public List getArgumentsSetFromPropertiesFile()
{
return Collections.unmodifiableList(argumentsSetFromPropertiesFile);
}
/**
* Indicates whether the comment listing arguments obtained from a properties
* file should be suppressed.
*
* @return {@code true} if the comment listing arguments obtained from a
* properties file should be suppressed, or {@code false} if not.
*/
public boolean suppressPropertiesFileComment()
{
final BooleanArgument arg =
getBooleanArgument(ARG_NAME_SUPPRESS_PROPERTIES_FILE_COMMENT);
return ((arg != null) && arg.isPresent());
}
/**
* Creates a copy of this argument parser that is "clean" and appears as if it
* has not been used to parse an argument set. The new parser will have all
* of the same arguments and constraints as this parser.
*
* @return The "clean" copy of this argument parser.
*/
@NotNull()
public ArgumentParser getCleanCopy()
{
return new ArgumentParser(this, null);
}
/**
* Parses the provided set of arguments.
*
* @param args An array containing the argument information to parse. It
* must not be {@code null}.
*
* @throws ArgumentException If a problem occurs while attempting to parse
* the argument information.
*/
public void parse(@NotNull final String[] args)
throws ArgumentException
{
// Iterate through the provided args strings and process them.
ArgumentParser subCommandParser = null;
boolean inTrailingArgs = false;
String subCommandName = null;
final AtomicBoolean skipFinalValidation = new AtomicBoolean(false);
for (int i=0; i < args.length; i++)
{
final String s = args[i];
if (inTrailingArgs)
{
if (maxTrailingArgs == 0)
{
throw new ArgumentException(ERR_PARSER_TRAILING_ARGS_NOT_ALLOWED.get(
s, commandName));
}
else if (trailingArgs.size() >= maxTrailingArgs)
{
throw new ArgumentException(ERR_PARSER_TOO_MANY_TRAILING_ARGS.get(s,
commandName, maxTrailingArgs));
}
else
{
trailingArgs.add(s);
}
}
else if (s.equals("--"))
{
// This signifies the end of the named arguments and the beginning of
// the trailing arguments.
inTrailingArgs = true;
}
else if (s.startsWith("--"))
{
// There may be an equal sign to separate the name from the value.
final String argName;
final int equalPos = s.indexOf('=');
if (equalPos > 0)
{
argName = s.substring(2, equalPos);
}
else
{
argName = s.substring(2);
}
final String lowerName = StaticUtils.toLowerCase(argName);
Argument a = namedArgsByLongID.get(lowerName);
if ((a == null) && (subCommandParser != null))
{
a = subCommandParser.namedArgsByLongID.get(lowerName);
}
if (a == null)
{
throw new ArgumentException(ERR_PARSER_NO_SUCH_LONG_ID.get(argName));
}
else if (a.isUsageArgument())
{
if (skipFinalValidationBecauseOfArgument(a))
{
skipFinalValidation.set(true);
}
}
a.incrementOccurrences();
if (a.takesValue())
{
if (equalPos > 0)
{
a.addValue(s.substring(equalPos+1));
}
else
{
i++;
if (i >= args.length)
{
throw new ArgumentException(ERR_PARSER_LONG_ARG_MISSING_VALUE.get(
argName));
}
else
{
a.addValue(args[i]);
}
}
}
else
{
if (equalPos > 0)
{
throw new ArgumentException(
ERR_PARSER_LONG_ARG_DOESNT_TAKE_VALUE.get(argName));
}
}
}
else if (s.startsWith("-"))
{
if (s.length() == 1)
{
throw new ArgumentException(ERR_PARSER_UNEXPECTED_DASH.get());
}
else if (s.length() == 2)
{
final char c = s.charAt(1);
Argument a = namedArgsByShortID.get(c);
if ((a == null) && (subCommandParser != null))
{
a = subCommandParser.namedArgsByShortID.get(c);
}
if (a == null)
{
throw new ArgumentException(ERR_PARSER_NO_SUCH_SHORT_ID.get(c));
}
else if (a.isUsageArgument())
{
if (skipFinalValidationBecauseOfArgument(a))
{
skipFinalValidation.set(true);
}
}
a.incrementOccurrences();
if (a.takesValue())
{
i++;
if (i >= args.length)
{
throw new ArgumentException(
ERR_PARSER_SHORT_ARG_MISSING_VALUE.get(c));
}
else
{
a.addValue(args[i]);
}
}
}
else
{
char c = s.charAt(1);
Argument a = namedArgsByShortID.get(c);
if ((a == null) && (subCommandParser != null))
{
a = subCommandParser.namedArgsByShortID.get(c);
}
if (a == null)
{
throw new ArgumentException(ERR_PARSER_NO_SUCH_SHORT_ID.get(c));
}
else if (a.isUsageArgument())
{
if (skipFinalValidationBecauseOfArgument(a))
{
skipFinalValidation.set(true);
}
}
a.incrementOccurrences();
if (a.takesValue())
{
a.addValue(s.substring(2));
}
else
{
// The rest of the characters in the string must also resolve to
// arguments that don't take values.
for (int j=2; j < s.length(); j++)
{
c = s.charAt(j);
a = namedArgsByShortID.get(c);
if ((a == null) && (subCommandParser != null))
{
a = subCommandParser.namedArgsByShortID.get(c);
}
if (a == null)
{
throw new ArgumentException(
ERR_PARSER_NO_SUBSEQUENT_SHORT_ARG.get(c, s));
}
else if (a.isUsageArgument())
{
if (skipFinalValidationBecauseOfArgument(a))
{
skipFinalValidation.set(true);
}
}
a.incrementOccurrences();
if (a.takesValue())
{
throw new ArgumentException(
ERR_PARSER_SUBSEQUENT_SHORT_ARG_TAKES_VALUE.get(
c, s));
}
}
}
}
}
else if (subCommands.isEmpty())
{
inTrailingArgs = true;
if (maxTrailingArgs == 0)
{
throw new ArgumentException(ERR_PARSER_TRAILING_ARGS_NOT_ALLOWED.get(
s, commandName));
}
else
{
trailingArgs.add(s);
}
}
else
{
if (selectedSubCommand == null)
{
subCommandName = s;
selectedSubCommand =
subCommandsByName.get(StaticUtils.toLowerCase(s));
if (selectedSubCommand == null)
{
throw new ArgumentException(ERR_PARSER_NO_SUCH_SUBCOMMAND.get(s,
commandName));
}
else
{
selectedSubCommand.setPresent();
subCommandParser = selectedSubCommand.getArgumentParser();
}
}
else
{
throw new ArgumentException(ERR_PARSER_CONFLICTING_SUBCOMMANDS.get(
subCommandName, s));
}
}
}
// Perform any appropriate processing related to the use of a properties
// file.
if (! handlePropertiesFile(skipFinalValidation))
{
return;
}
// If a usage argument was provided, then no further validation should be
// performed.
if (skipFinalValidation.get())
{
return;
}
// If any subcommands are defined, then one must have been provided.
if ((! subCommands.isEmpty()) && (selectedSubCommand == null))
{
throw new ArgumentException(
ERR_PARSER_MISSING_SUBCOMMAND.get(commandName));
}
doFinalValidation(this);
if (selectedSubCommand != null)
{
doFinalValidation(selectedSubCommand.getArgumentParser());
}
}
/**
* Sets the command-line tool with which this argument parser is associated.
*
* @param commandLineTool The command-line tool with which this argument
* parser is associated. It may be {@code null} if
* there is no associated command-line tool.
*/
public void setCommandLineTool(
@Nullable final CommandLineTool commandLineTool)
{
this.commandLineTool = commandLineTool;
}
/**
* Performs the final validation for the provided argument parser.
*
* @param parser The argument parser for which to perform the final
* validation.
*
* @throws ArgumentException If a validation problem is encountered.
*/
private static void doFinalValidation(@NotNull final ArgumentParser parser)
throws ArgumentException
{
// Make sure that all required arguments have values.
for (final Argument a : parser.namedArgs)
{
if (a.isRequired() && (! a.isPresent()))
{
throw new ArgumentException(ERR_PARSER_MISSING_REQUIRED_ARG.get(
a.getIdentifierString()));
}
}
// Make sure that at least the minimum number of trailing arguments were
// provided.
if (parser.trailingArgs.size() < parser.minTrailingArgs)
{
throw new ArgumentException(ERR_PARSER_NOT_ENOUGH_TRAILING_ARGS.get(
parser.commandName, parser.minTrailingArgs,
parser.trailingArgsPlaceholder));
}
// Make sure that there are no dependent argument set conflicts.
for (final ObjectPair> p :
parser.dependentArgumentSets)
{
final Argument targetArg = p.getFirst();
if (targetArg.getNumOccurrences() > 0)
{
final Set argSet = p.getSecond();
boolean found = false;
for (final Argument a : argSet)
{
if (a.getNumOccurrences() > 0)
{
found = true;
break;
}
}
if (! found)
{
if (argSet.size() == 1)
{
throw new ArgumentException(
ERR_PARSER_DEPENDENT_CONFLICT_SINGLE.get(
targetArg.getIdentifierString(),
argSet.iterator().next().getIdentifierString()));
}
else
{
boolean first = true;
final StringBuilder buffer = new StringBuilder();
for (final Argument a : argSet)
{
if (first)
{
first = false;
}
else
{
buffer.append(", ");
}
buffer.append(a.getIdentifierString());
}
throw new ArgumentException(
ERR_PARSER_DEPENDENT_CONFLICT_MULTIPLE.get(
targetArg.getIdentifierString(), buffer.toString()));
}
}
}
}
// Make sure that there are no exclusive argument set conflicts.
for (final Set argSet : parser.exclusiveArgumentSets)
{
Argument setArg = null;
for (final Argument a : argSet)
{
if (a.getNumOccurrences() > 0)
{
if (setArg == null)
{
setArg = a;
}
else
{
throw new ArgumentException(ERR_PARSER_EXCLUSIVE_CONFLICT.get(
setArg.getIdentifierString(),
a.getIdentifierString()));
}
}
}
}
// Make sure that there are no required argument set conflicts.
for (final Set argSet : parser.requiredArgumentSets)
{
boolean found = false;
for (final Argument a : argSet)
{
if (a.getNumOccurrences() > 0)
{
found = true;
break;
}
}
if (! found)
{
boolean first = true;
final StringBuilder buffer = new StringBuilder();
for (final Argument a : argSet)
{
if (first)
{
first = false;
}
else
{
buffer.append(", ");
}
buffer.append(a.getIdentifierString());
}
throw new ArgumentException(ERR_PARSER_REQUIRED_CONFLICT.get(
buffer.toString()));
}
}
}
/**
* Indicates whether the provided argument is one that indicates that the
* parser should skip all validation except that performed when assigning
* values from command-line arguments. Validation that will be skipped
* includes ensuring that all required arguments have values, ensuring that
* the minimum number of trailing arguments were provided, and ensuring that
* there were no dependent/exclusive/required argument set conflicts.
*
* @param a The argument for which to make the determination.
*
* @return {@code true} if the provided argument is one that indicates that
* final validation should be skipped, or {@code false} if not.
*/
private static boolean skipFinalValidationBecauseOfArgument(
@NotNull final Argument a)
{
// We will skip final validation for all usage arguments except the ones
// used for interacting with properties and output files.
if (ARG_NAME_PROPERTIES_FILE_PATH.equals(a.getLongIdentifier()) ||
ARG_NAME_NO_PROPERTIES_FILE.equals(a.getLongIdentifier()) ||
ARG_NAME_SUPPRESS_PROPERTIES_FILE_COMMENT.equals(
a.getLongIdentifier()) ||
ARG_NAME_OUTPUT_FILE.equals(a.getLongIdentifier()) ||
ARG_NAME_TEE_OUTPUT.equals(a.getLongIdentifier()))
{
return false;
}
return a.isUsageArgument();
}
/**
* Performs any appropriate properties file processing for this argument
* parser.
*
* @param skipFinalValidation A flag that indicates whether to skip final
* validation because a qualifying usage argument
* was provided.
*
* @return {@code true} if the tool should continue processing, or
* {@code false} if it should return immediately.
*
* @throws ArgumentException If a problem is encountered while attempting
* to parse a properties file or update arguments
* with the values contained in it.
*/
private boolean handlePropertiesFile(
@NotNull final AtomicBoolean skipFinalValidation)
throws ArgumentException
{
final BooleanArgument noPropertiesFile;
final FileArgument generatePropertiesFile;
final FileArgument propertiesFilePath;
try
{
propertiesFilePath = getFileArgument(ARG_NAME_PROPERTIES_FILE_PATH);
generatePropertiesFile =
getFileArgument(ARG_NAME_GENERATE_PROPERTIES_FILE);
noPropertiesFile = getBooleanArgument(ARG_NAME_NO_PROPERTIES_FILE);
}
catch (final Exception e)
{
Debug.debugException(e);
// This should only ever happen if the argument parser has an argument
// with a name that conflicts with one of the properties file arguments
// but isn't of the right type. In this case, we'll assume that no
// properties file will be used.
return true;
}
// If any of the properties file arguments isn't defined, then we'll assume
// that no properties file will be used.
if ((propertiesFilePath == null) || (generatePropertiesFile == null) ||
(noPropertiesFile == null))
{
return true;
}
// If the noPropertiesFile argument is present, then don't do anything but
// make sure that neither of the other arguments was specified.
if (noPropertiesFile.isPresent())
{
if (propertiesFilePath.isPresent())
{
throw new ArgumentException(ERR_PARSER_EXCLUSIVE_CONFLICT.get(
noPropertiesFile.getIdentifierString(),
propertiesFilePath.getIdentifierString()));
}
else if (generatePropertiesFile.isPresent())
{
throw new ArgumentException(ERR_PARSER_EXCLUSIVE_CONFLICT.get(
noPropertiesFile.getIdentifierString(),
generatePropertiesFile.getIdentifierString()));
}
else
{
return true;
}
}
// If the generatePropertiesFile argument is present, then make sure the
// propertiesFilePath argument is not set and generate the output.
if (generatePropertiesFile.isPresent())
{
if (propertiesFilePath.isPresent())
{
throw new ArgumentException(ERR_PARSER_EXCLUSIVE_CONFLICT.get(
generatePropertiesFile.getIdentifierString(),
propertiesFilePath.getIdentifierString()));
}
else
{
generatePropertiesFile(
generatePropertiesFile.getValue().getAbsolutePath());
return false;
}
}
// If the propertiesFilePath argument is present, then try to make use of
// the specified file.
if (propertiesFilePath.isPresent())
{
final File propertiesFile = propertiesFilePath.getValue();
if (propertiesFile.exists() && propertiesFile.isFile())
{
handlePropertiesFile(propertiesFilePath.getValue(),
skipFinalValidation);
}
else
{
throw new ArgumentException(
ERR_PARSER_NO_SUCH_PROPERTIES_FILE.get(
propertiesFilePath.getIdentifierString(),
propertiesFile.getAbsolutePath()));
}
return true;
}
// We may still use a properties file if the path was specified in either a
// JVM property or an environment variable. If both are defined, the JVM
// property will take precedence. If a property or environment variable
// specifies an invalid value, then we'll just ignore it.
String path = StaticUtils.getSystemProperty(
PROPERTY_DEFAULT_PROPERTIES_FILE_PATH);
if (path == null)
{
path = StaticUtils.getEnvironmentVariable(
ENV_DEFAULT_PROPERTIES_FILE_PATH);
}
if (path != null)
{
final File propertiesFile = new File(path);
if (propertiesFile.exists() && propertiesFile.isFile())
{
handlePropertiesFile(propertiesFile, skipFinalValidation);
}
}
return true;
}
/**
* Write an empty properties file for this argument parser to the specified
* path.
*
* @param path The path to the properties file to be written.
*
* @throws ArgumentException If a problem is encountered while writing the
* properties file.
*/
private void generatePropertiesFile(@NotNull final String path)
throws ArgumentException
{
final PrintWriter w;
try
{
// The java.util.Properties specification states that properties files
// should be read using the ISO 8859-1 character set.
w = new PrintWriter(new OutputStreamWriter(new FileOutputStream(path),
StandardCharsets.ISO_8859_1));
}
catch (final Exception e)
{
Debug.debugException(e);
throw new ArgumentException(
ERR_PARSER_GEN_PROPS_CANNOT_OPEN_FILE.get(path,
StaticUtils.getExceptionMessage(e)),
e);
}
try
{
wrapComment(w, INFO_PARSER_GEN_PROPS_HEADER_1.get(commandName));
w.println('#');
wrapComment(w,
INFO_PARSER_GEN_PROPS_HEADER_2.get(commandName,
ARG_NAME_PROPERTIES_FILE_PATH,
PROPERTY_DEFAULT_PROPERTIES_FILE_PATH,
ENV_DEFAULT_PROPERTIES_FILE_PATH, ARG_NAME_NO_PROPERTIES_FILE));
w.println('#');
wrapComment(w, INFO_PARSER_GEN_PROPS_HEADER_3.get());
w.println('#');
wrapComment(w, INFO_PARSER_GEN_PROPS_HEADER_4.get());
w.println('#');
wrapComment(w, INFO_PARSER_GEN_PROPS_HEADER_5.get(commandName));
for (final Argument a : getNamedArguments())
{
writeArgumentProperties(w, null, a);
}
for (final SubCommand sc : getSubCommands())
{
for (final Argument a : sc.getArgumentParser().getNamedArguments())
{
writeArgumentProperties(w, sc, a);
}
}
}
finally
{
w.close();
}
}
/**
* Writes information about the provided argument to the given writer.
*
* @param w The writer to which the properties should be written. It must
* not be {@code null}.
* @param sc The subcommand with which the argument is associated. It may
* be {@code null} if the provided argument is a global argument.
* @param a The argument for which to write the properties. It must not be
* {@code null}.
*/
private void writeArgumentProperties(@NotNull final PrintWriter w,
@Nullable final SubCommand sc,
@NotNull final Argument a)
{
if (a.isUsageArgument() || a.isHidden())
{
return;
}
w.println();
w.println();
wrapComment(w, a.getDescription());
w.println('#');
final String constraints = a.getValueConstraints();
if ((constraints != null) && (! constraints.isEmpty()) &&
(! (a instanceof BooleanArgument)))
{
wrapComment(w, constraints);
w.println('#');
}
final String identifier;
if (a.getLongIdentifier() != null)
{
identifier = a.getLongIdentifier();
}
else
{
identifier = a.getIdentifierString();
}
String placeholder = a.getValuePlaceholder();
if (placeholder == null)
{
if (a instanceof BooleanArgument)
{
placeholder = "{true|false}";
}
else
{
placeholder = "";
}
}
final String propertyName;
if (sc == null)
{
propertyName = commandName + '.' + identifier;
}
else
{
propertyName = commandName + '.' + sc.getPrimaryName() + '.' + identifier;
}
w.println("# " + propertyName + '=' + placeholder);
if (a.isPresent())
{
for (final String s : a.getValueStringRepresentations(false))
{
w.println(propertyName + '=' + escapePropertyValue(s));
}
}
}
/**
* Retrieves a string that represents an escaped representation of the
* provided property value. The following characters will be escaped by
* preceding them with a backslash:
*
*
Backslash (\\)
*
Tab (\t)
*
Carriage return (\r)
*
Newline (\n)
*
Form feed (\f)
*
*
* Note that even though the Java Properties implementation will also escape
* equal signs, colons, exclamation points, and octothorpes when writing a
* properties file, it will also handle reading property values with unescaped
* versions of those characters, so they will remain unescaped.
*
* @param value The value to be escaped. It must not be {@code null}.
*
* @return A string that represents an escaped representation of the provided
* property value.
*/
@NotNull()
public static String escapePropertyValue(@NotNull final String value)
{
final StringBuilder buffer = new StringBuilder(value.length());
for (int i=0; i < value.length(); i++)
{
final char c = value.charAt(i);
switch (c)
{
case '\\':
buffer.append("\\\\");
break;
case '\t':
buffer.append("\\t");
break;
case '\r':
buffer.append("\\r");
break;
case '\n':
buffer.append("\\n");
break;
case '\f':
buffer.append("\\f");
break;
default:
buffer.append(c);
break;
}
}
return buffer.toString();
}
/**
* Wraps the given string and writes it as a comment to the provided writer.
*
* @param w The writer to use to write the wrapped and commented string.
* @param s The string to be wrapped and written.
*/
private static void wrapComment(@NotNull final PrintWriter w,
@NotNull final String s)
{
for (final String line : StaticUtils.wrapLine(s, 77))
{
w.println("# " + line);
}
}
/**
* Reads the contents of the specified properties file and updates the
* configured arguments as appropriate.
*
* @param propertiesFile The properties file to process.
* @param skipFinalValidation A flag that indicates whether to skip final
* validation because a qualifying usage argument
* was provided.
*
* @throws ArgumentException If a problem is encountered while examining the
* properties file, or while trying to assign a
* property value to a corresponding argument.
*/
private void handlePropertiesFile(@NotNull final File propertiesFile,
@NotNull final AtomicBoolean skipFinalValidation)
throws ArgumentException
{
final String propertiesFilePath = propertiesFile.getAbsolutePath();
InputStream inputStream = null;
final BufferedReader reader;
try
{
inputStream = new FileInputStream(propertiesFile);
// Handle the case in which the properties file may be encrypted.
final List cachedPasswords;
final PrintStream err;
final PrintStream out;
final CommandLineTool tool = commandLineTool;
if (tool == null)
{
cachedPasswords = Collections.emptyList();
out = System.out;
err = System.err;
}
else
{
cachedPasswords =
tool.getPasswordFileReader().getCachedEncryptionPasswords();
out = tool.getOut();
err = tool.getErr();
}
final ObjectPair encryptionData =
ToolUtils.getPossiblyPassphraseEncryptedInputStream(inputStream,
cachedPasswords, true,
INFO_PARSER_PROMPT_FOR_PROP_FILE_ENC_PW.get(
propertiesFile.getAbsolutePath()),
ERR_PARSER_WRONG_PROP_FILE_ENC_PW.get(
propertiesFile.getAbsolutePath()),
out, err);
inputStream = encryptionData.getFirst();
if ((tool != null) && (encryptionData.getSecond() != null))
{
tool.getPasswordFileReader().addToEncryptionPasswordCache(
encryptionData.getSecond());
}
// Handle the case in which the properties file may be compressed.
inputStream = ToolUtils.getPossiblyGZIPCompressedInputStream(inputStream);
// The java.util.Properties specification states that properties files
// should be read using the ISO 8859-1 character set, and that characters
// that cannot be encoded in that format should be represented using
// Unicode escapes that start with a backslash, a lowercase letter "u",
// and four hexadecimal digits. To provide compatibility with the Java
// Properties file format (except we also support the same property
// appearing multiple times), we will also use that encoding and will
// support Unicode escape sequences.
reader = new BufferedReader(new InputStreamReader(inputStream,
StandardCharsets.ISO_8859_1));
}
catch (final Exception e)
{
if (inputStream != null)
{
try
{
inputStream.close();
}
catch (final Exception e2)
{
Debug.debugException(e2);
}
}
Debug.debugException(e);
throw new ArgumentException(
ERR_PARSER_CANNOT_OPEN_PROP_FILE.get(propertiesFilePath,
StaticUtils.getExceptionMessage(e)),
e);
}
try
{
// Read all of the lines of the file, ignoring comments and unwrapping
// properties that span multiple lines.
boolean lineIsContinued = false;
int lineNumber = 0;
final ArrayList> propertyLines =
new ArrayList<>(10);
while (true)
{
String line;
try
{
line = reader.readLine();
lineNumber++;
}
catch (final Exception e)
{
Debug.debugException(e);
throw new ArgumentException(
ERR_PARSER_ERROR_READING_PROP_FILE.get(propertiesFilePath,
StaticUtils.getExceptionMessage(e)),
e);
}
// If the line is null, then we've reached the end of the file. If we
// expect a previous line to have been continued, then this is an error.
if (line == null)
{
if (lineIsContinued)
{
throw new ArgumentException(
ERR_PARSER_PROP_FILE_MISSING_CONTINUATION.get(
(lineNumber-1), propertiesFilePath));
}
break;
}
// See if the line has any leading whitespace, and if so then trim it
// off. If there is leading whitespace, then make sure that we expect
// the previous line to be continued.
final int initialLength = line.length();
line = StaticUtils.trimLeading(line);
final boolean hasLeadingWhitespace = (line.length() < initialLength);
if (hasLeadingWhitespace && (! lineIsContinued))
{
throw new ArgumentException(
ERR_PARSER_PROP_FILE_UNEXPECTED_LEADING_SPACE.get(
propertiesFilePath, lineNumber));
}
// If the line is empty or starts with "#", then skip it. But make sure
// we didn't expect the previous line to be continued.
if ((line.isEmpty()) || line.startsWith("#"))
{
if (lineIsContinued)
{
throw new ArgumentException(
ERR_PARSER_PROP_FILE_MISSING_CONTINUATION.get(
(lineNumber-1), propertiesFilePath));
}
continue;
}
// See if the line ends with a backslash and if so then trim it off.
final boolean hasTrailingBackslash = line.endsWith("\\");
if (line.endsWith("\\"))
{
line = line.substring(0, (line.length() - 1));
}
// If the previous line needs to be continued, then append the new line
// to it. Otherwise, add it as a new line.
if (lineIsContinued)
{
propertyLines.get(propertyLines.size() - 1).getSecond().append(line);
}
else
{
propertyLines.add(
new ObjectPair<>(lineNumber, new StringBuilder(line)));
}
lineIsContinued = hasTrailingBackslash;
}
// Parse all of the lines into a map of identifiers and their
// corresponding values.
propertiesFileUsed = propertiesFile;
if (propertyLines.isEmpty())
{
return;
}
final HashMap> propertyMap =
new HashMap<>(StaticUtils.computeMapCapacity(propertyLines.size()));
for (final ObjectPair p : propertyLines)
{
lineNumber = p.getFirst();
final String line = handleUnicodeEscapes(propertiesFilePath, lineNumber,
p.getSecond());
final int equalPos = line.indexOf('=');
if (equalPos <= 0)
{
throw new ArgumentException(ERR_PARSER_MALFORMED_PROP_LINE.get(
propertiesFilePath, lineNumber, line));
}
final String propertyName = line.substring(0, equalPos).trim();
final String propertyValue = line.substring(equalPos+1).trim();
if (propertyValue.isEmpty())
{
// The property doesn't have a value, so we can ignore it.
continue;
}
// An argument can have multiple identifiers, and we will allow any of
// them to be used to reference it. To deal with this, we'll map the
// argument identifier to its corresponding argument and then use the
// preferred identifier for that argument in the map. The same applies
// to subcommand names.
boolean prefixedWithToolName = false;
boolean prefixedWithSubCommandName = false;
Argument a = getNamedArgument(propertyName);
if (a == null)
{
// It could be that the argument name was prefixed with the tool name.
// Check to see if that was the case.
if (propertyName.startsWith(commandName + '.'))
{
prefixedWithToolName = true;
String basePropertyName =
propertyName.substring(commandName.length()+1);
a = getNamedArgument(basePropertyName);
if (a == null)
{
final int periodPos = basePropertyName.indexOf('.');
if (periodPos > 0)
{
final String subCommandName =
basePropertyName.substring(0, periodPos);
if ((selectedSubCommand != null) &&
selectedSubCommand.hasName(subCommandName))
{
prefixedWithSubCommandName = true;
basePropertyName = basePropertyName.substring(periodPos+1);
a = selectedSubCommand.getArgumentParser().getNamedArgument(
basePropertyName);
}
}
else if (selectedSubCommand != null)
{
a = selectedSubCommand.getArgumentParser().getNamedArgument(
basePropertyName);
}
}
}
else if (selectedSubCommand != null)
{
a = selectedSubCommand.getArgumentParser().getNamedArgument(
propertyName);
}
}
if (a == null)
{
// This could mean that there's a typo in the property name, but it's
// more likely the case that the property is for a different tool. In
// either case, we'll ignore it.
continue;
}
final String canonicalPropertyName;
if (prefixedWithToolName)
{
if (prefixedWithSubCommandName)
{
canonicalPropertyName = commandName + '.' +
selectedSubCommand.getPrimaryName() + '.' +
a.getIdentifierString();
}
else
{
canonicalPropertyName = commandName + '.' + a.getIdentifierString();
}
}
else
{
canonicalPropertyName = a.getIdentifierString();
}
ArrayList valueList = propertyMap.get(canonicalPropertyName);
if (valueList == null)
{
valueList = new ArrayList<>(5);
propertyMap.put(canonicalPropertyName, valueList);
}
valueList.add(propertyValue);
}
// Iterate through all of the named arguments for the argument parser and
// see if we should use the properties to assign values to any of the
// arguments that weren't provided on the command line.
setArgsFromPropertiesFile(propertyMap, false, skipFinalValidation);
// If there is a selected subcommand, then iterate through all of its
// arguments.
if (selectedSubCommand != null)
{
setArgsFromPropertiesFile(propertyMap, true, skipFinalValidation);
}
}
finally
{
try
{
reader.close();
}
catch (final Exception e)
{
Debug.debugException(e);
}
}
}
/**
* Retrieves a string that contains the contents of the provided buffer, but
* with any Unicode escape sequences converted to the appropriate character
* representation, and any other escapes having the initial backslash
* removed.
*
* @param propertiesFilePath The path to the properties file being written.
* It must not be {@code null}.
* @param lineNumber The line number on which the property
* definition starts.
* @param buffer The buffer containing the data to be processed.
* It must not be {@code null} but may be empty.
*
* @return A string that contains the contents of the provided buffer, but
* with any Unicode escape sequences converted to the appropriate
* character representation.
*
* @throws ArgumentException If a malformed Unicode escape sequence is
* encountered.
*/
@NotNull()
static String handleUnicodeEscapes(@NotNull final String propertiesFilePath,
final int lineNumber,
@NotNull final StringBuilder buffer)
throws ArgumentException
{
int pos = 0;
while (pos < buffer.length())
{
final char c = buffer.charAt(pos);
if (c == '\\')
{
if (pos <= (buffer.length() - 5))
{
final char nextChar = buffer.charAt(pos+1);
if ((nextChar == 'u') || (nextChar == 'U'))
{
try
{
final String hexDigits = buffer.substring(pos+2, pos+6);
final byte[] bytes = StaticUtils.fromHex(hexDigits);
final int i = ((bytes[0] & 0xFF) << 8) | (bytes[1] & 0xFF);
buffer.setCharAt(pos, (char) i);
for (int j=0; j < 5; j++)
{
buffer.deleteCharAt(pos+1);
}
}
catch (final Exception e)
{
Debug.debugException(e);
throw new ArgumentException(
ERR_PARSER_MALFORMED_UNICODE_ESCAPE.get(propertiesFilePath,
lineNumber),
e);
}
}
else
{
buffer.deleteCharAt(pos);
}
}
}
pos++;
}
return buffer.toString();
}
/**
* Sets the values of any arguments not provided on the command line but
* defined in the properties file.
*
* @param propertyMap A map of properties read from the properties
* file.
* @param useSubCommand Indicates whether to use the argument parser
* associated with the selected subcommand rather
* than the global argument parser.
* @param skipFinalValidation A flag that indicates whether to skip final
* validation because a qualifying usage argument
* was provided.
*
* @throws ArgumentException If a problem is encountered while examining the
* properties file, or while trying to assign a
* property value to a corresponding argument.
*/
private void setArgsFromPropertiesFile(
@NotNull final Map> propertyMap,
final boolean useSubCommand,
@NotNull final AtomicBoolean skipFinalValidation)
throws ArgumentException
{
final ArgumentParser p;
if (useSubCommand)
{
p = selectedSubCommand.getArgumentParser();
}
else
{
p = this;
}
for (final Argument a : p.namedArgs)
{
// If the argument was provided on the command line, then that will always
// override anything that might be in the properties file.
if (a.getNumOccurrences() > 0)
{
continue;
}
// If the argument is part of an exclusive argument set, and if one of
// the other arguments in that set was provided on the command line, then
// don't look in the properties file for a value for the argument.
boolean exclusiveArgumentHasValue = false;
exclusiveArgumentLoop:
for (final Set exclusiveArgumentSet : exclusiveArgumentSets)
{
if (exclusiveArgumentSet.contains(a))
{
for (final Argument exclusiveArg : exclusiveArgumentSet)
{
if (exclusiveArg.getNumOccurrences() > 0)
{
exclusiveArgumentHasValue = true;
break exclusiveArgumentLoop;
}
}
}
}
if (exclusiveArgumentHasValue)
{
continue;
}
// If we should use a subcommand, then see if the properties file has a
// property that is specific to the selected subcommand. Then fall back
// to a property that is specific to the tool, and finally fall back to
// checking for a set of values that are generic to any tool that has an
// argument with that name.
List values = null;
if (useSubCommand)
{
values = propertyMap.get(commandName + '.' +
selectedSubCommand.getPrimaryName() + '.' +
a.getIdentifierString());
}
if (values == null)
{
values = propertyMap.get(commandName + '.' + a.getIdentifierString());
}
if (values == null)
{
values = propertyMap.get(a.getIdentifierString());
}
if (values != null)
{
for (final String value : values)
{
if (a instanceof BooleanArgument)
{
// We'll treat this as a BooleanValueArgument.
final BooleanValueArgument bva = new BooleanValueArgument(
a.getShortIdentifier(), a.getLongIdentifier(), false, null,
a.getDescription());
bva.addValue(value);
if (bva.getValue())
{
a.incrementOccurrences();
argumentsSetFromPropertiesFile.add(a.getIdentifierString());
}
}
else
{
a.addValue(value);
a.incrementOccurrences();
argumentsSetFromPropertiesFile.add(a.getIdentifierString());
if (a.isSensitive())
{
argumentsSetFromPropertiesFile.add("***REDACTED***");
}
else
{
argumentsSetFromPropertiesFile.add(value);
}
}
}
if (a.isUsageArgument() && skipFinalValidationBecauseOfArgument(a))
{
skipFinalValidation.set(true);
}
}
}
}
/**
* Retrieves lines that make up the usage information for this program,
* optionally wrapping long lines.
*
* @param maxWidth The maximum line width to use for the output. If this is
* less than or equal to zero, then no wrapping will be
* performed.
*
* @return The lines that make up the usage information for this program.
*/
@NotNull()
public List getUsage(final int maxWidth)
{
// If a subcommand was selected, then provide usage specific to that
// subcommand.
if (selectedSubCommand != null)
{
return getSubCommandUsage(maxWidth);
}
// First is a description of the command.
final ArrayList lines = new ArrayList<>(100);
lines.addAll(StaticUtils.wrapLine(commandDescription, maxWidth));
lines.add("");
for (final String additionalDescriptionParagraph :
additionalCommandDescriptionParagraphs)
{
lines.addAll(StaticUtils.wrapLine(additionalDescriptionParagraph,
maxWidth));
lines.add("");
}
// If the tool supports subcommands, and if there are fewer than 10
// subcommands, then display them inline.
if ((! subCommands.isEmpty()) && (subCommands.size() < 10))
{
lines.add(INFO_USAGE_SUBCOMMANDS_HEADER.get());
lines.add("");
for (final SubCommand sc : subCommands)
{
final StringBuilder nameBuffer = new StringBuilder();
nameBuffer.append(" ");
final Iterator nameIterator = sc.getNames(false).iterator();
while (nameIterator.hasNext())
{
nameBuffer.append(nameIterator.next());
if (nameIterator.hasNext())
{
nameBuffer.append(", ");
}
}
lines.add(nameBuffer.toString());
for (final String descriptionLine :
StaticUtils.wrapLine(sc.getDescription(), (maxWidth - 4)))
{
lines.add(" " + descriptionLine);
}
lines.add("");
}
}
// Next comes the usage. It may include neither, either, or both of the
// set of options and trailing arguments.
if (! subCommands.isEmpty())
{
lines.addAll(StaticUtils.wrapLine(
INFO_USAGE_SUBCOMMAND_USAGE.get(commandName), maxWidth));
}
else if (namedArgs.isEmpty())
{
if (maxTrailingArgs == 0)
{
lines.addAll(StaticUtils.wrapLine(
INFO_USAGE_NOOPTIONS_NOTRAILING.get(commandName), maxWidth));
}
else
{
lines.addAll(StaticUtils.wrapLine(INFO_USAGE_NOOPTIONS_TRAILING.get(
commandName, trailingArgsPlaceholder), maxWidth));
}
}
else
{
if (maxTrailingArgs == 0)
{
lines.addAll(StaticUtils.wrapLine(
INFO_USAGE_OPTIONS_NOTRAILING.get(commandName), maxWidth));
}
else
{
lines.addAll(StaticUtils.wrapLine(INFO_USAGE_OPTIONS_TRAILING.get(
commandName, trailingArgsPlaceholder), maxWidth));
}
}
if (! namedArgs.isEmpty())
{
lines.add("");
lines.add(INFO_USAGE_OPTIONS_INCLUDE.get());
// If there are any argument groups, then collect the arguments in those
// groups.
boolean hasRequired = false;
final LinkedHashMap> argumentsByGroup =
new LinkedHashMap<>(StaticUtils.computeMapCapacity(10));
final ArrayList argumentsWithoutGroup =
new ArrayList<>(namedArgs.size());
final ArrayList usageArguments =
new ArrayList<>(namedArgs.size());
for (final Argument a : namedArgs)
{
if (a.isHidden())
{
// This argument shouldn't be included in the usage output.
continue;
}
if (a.isRequired() && (! a.hasDefaultValue()))
{
hasRequired = true;
}
final String argumentGroup = a.getArgumentGroupName();
if (argumentGroup == null)
{
if (a.isUsageArgument())
{
usageArguments.add(a);
}
else
{
argumentsWithoutGroup.add(a);
}
}
else
{
List groupArgs = argumentsByGroup.get(argumentGroup);
if (groupArgs == null)
{
groupArgs = new ArrayList<>(10);
argumentsByGroup.put(argumentGroup, groupArgs);
}
groupArgs.add(a);
}
}
// Iterate through the defined argument groups and display usage
// information for each of them.
for (final Map.Entry> e :
argumentsByGroup.entrySet())
{
lines.add("");
lines.add(" " + e.getKey());
lines.add("");
for (final Argument a : e.getValue())
{
getArgUsage(a, lines, true, maxWidth);
}
}
if (! argumentsWithoutGroup.isEmpty())
{
if (argumentsByGroup.isEmpty())
{
for (final Argument a : argumentsWithoutGroup)
{
getArgUsage(a, lines, false, maxWidth);
}
}
else
{
lines.add("");
lines.add(" " + INFO_USAGE_UNGROUPED_ARGS.get());
lines.add("");
for (final Argument a : argumentsWithoutGroup)
{
getArgUsage(a, lines, true, maxWidth);
}
}
}
if (! usageArguments.isEmpty())
{
if (argumentsByGroup.isEmpty())
{
for (final Argument a : usageArguments)
{
getArgUsage(a, lines, false, maxWidth);
}
}
else
{
lines.add("");
lines.add(" " + INFO_USAGE_USAGE_ARGS.get());
lines.add("");
for (final Argument a : usageArguments)
{
getArgUsage(a, lines, true, maxWidth);
}
}
}
if (hasRequired)
{
lines.add("");
if (argumentsByGroup.isEmpty())
{
lines.add("* " + INFO_USAGE_ARG_IS_REQUIRED.get());
}
else
{
lines.add(" * " + INFO_USAGE_ARG_IS_REQUIRED.get());
}
}
}
return lines;
}
/**
* Retrieves lines that make up the usage information for the selected
* subcommand.
*
* @param maxWidth The maximum line width to use for the output. If this is
* less than or equal to zero, then no wrapping will be
* performed.
*
* @return The lines that make up the usage information for the selected
* subcommand.
*/
@NotNull()
private List getSubCommandUsage(final int maxWidth)
{
// First is a description of the subcommand.
final ArrayList lines = new ArrayList<>(100);
lines.addAll(
StaticUtils.wrapLine(selectedSubCommand.getDescription(), maxWidth));
lines.add("");
// Next comes the usage.
lines.addAll(StaticUtils.wrapLine(INFO_SUBCOMMAND_USAGE_OPTIONS.get(
commandName, selectedSubCommand.getPrimaryName()), maxWidth));
final ArgumentParser parser = selectedSubCommand.getArgumentParser();
if (! parser.namedArgs.isEmpty())
{
lines.add("");
lines.add(INFO_USAGE_OPTIONS_INCLUDE.get());
// If there are any argument groups, then collect the arguments in those
// groups.
boolean hasRequired = false;
final LinkedHashMap> argumentsByGroup =
new LinkedHashMap<>(StaticUtils.computeMapCapacity(10));
final ArrayList argumentsWithoutGroup =
new ArrayList<>(parser.namedArgs.size());
final ArrayList usageArguments =
new ArrayList<>(parser.namedArgs.size());
for (final Argument a : parser.namedArgs)
{
if (a.isHidden())
{
// This argument shouldn't be included in the usage output.
continue;
}
if (a.isRequired() && (! a.hasDefaultValue()))
{
hasRequired = true;
}
final String argumentGroup = a.getArgumentGroupName();
if (argumentGroup == null)
{
if (a.isUsageArgument())
{
usageArguments.add(a);
}
else
{
argumentsWithoutGroup.add(a);
}
}
else
{
List groupArgs = argumentsByGroup.get(argumentGroup);
if (groupArgs == null)
{
groupArgs = new ArrayList<>(10);
argumentsByGroup.put(argumentGroup, groupArgs);
}
groupArgs.add(a);
}
}
// Iterate through the defined argument groups and display usage
// information for each of them.
for (final Map.Entry> e :
argumentsByGroup.entrySet())
{
lines.add("");
lines.add(" " + e.getKey());
lines.add("");
for (final Argument a : e.getValue())
{
getArgUsage(a, lines, true, maxWidth);
}
}
if (! argumentsWithoutGroup.isEmpty())
{
if (argumentsByGroup.isEmpty())
{
for (final Argument a : argumentsWithoutGroup)
{
getArgUsage(a, lines, false, maxWidth);
}
}
else
{
lines.add("");
lines.add(" " + INFO_USAGE_UNGROUPED_ARGS.get());
lines.add("");
for (final Argument a : argumentsWithoutGroup)
{
getArgUsage(a, lines, true, maxWidth);
}
}
}
if (! usageArguments.isEmpty())
{
if (argumentsByGroup.isEmpty())
{
for (final Argument a : usageArguments)
{
getArgUsage(a, lines, false, maxWidth);
}
}
else
{
lines.add("");
lines.add(" " + INFO_USAGE_USAGE_ARGS.get());
lines.add("");
for (final Argument a : usageArguments)
{
getArgUsage(a, lines, true, maxWidth);
}
}
}
if (hasRequired)
{
lines.add("");
if (argumentsByGroup.isEmpty())
{
lines.add("* " + INFO_USAGE_ARG_IS_REQUIRED.get());
}
else
{
lines.add(" * " + INFO_USAGE_ARG_IS_REQUIRED.get());
}
}
}
return lines;
}
/**
* Adds usage information for the provided argument to the given list.
*
* @param a The argument for which to get the usage information.
* @param lines The list to which the resulting lines should be added.
* @param indent Indicates whether to indent each line.
* @param maxWidth The maximum width of each line, in characters.
*/
private static void getArgUsage(@NotNull final Argument a,
@NotNull final List lines,
final boolean indent, final int maxWidth)
{
final StringBuilder argLine = new StringBuilder();
if (indent && (maxWidth > 10))
{
if (a.isRequired() && (! a.hasDefaultValue()))
{
argLine.append(" * ");
}
else
{
argLine.append(" ");
}
}
else if (a.isRequired() && (! a.hasDefaultValue()))
{
argLine.append("* ");
}
boolean first = true;
for (final Character c : a.getShortIdentifiers(false))
{
if (first)
{
argLine.append('-');
first = false;
}
else
{
argLine.append(", -");
}
argLine.append(c);
}
for (final String s : a.getLongIdentifiers(false))
{
if (first)
{
argLine.append("--");
first = false;
}
else
{
argLine.append(", --");
}
argLine.append(s);
}
final String valuePlaceholder = a.getValuePlaceholder();
if (valuePlaceholder != null)
{
argLine.append(' ');
argLine.append(valuePlaceholder);
}
// If we need to wrap the argument line, then align the dashes on the left
// edge.
int subsequentLineWidth = maxWidth - 4;
if (subsequentLineWidth < 4)
{
subsequentLineWidth = maxWidth;
}
final List identifierLines =
StaticUtils.wrapLine(argLine.toString(), maxWidth,
subsequentLineWidth);
for (int i=0; i < identifierLines.size(); i++)
{
if (i == 0)
{
lines.add(identifierLines.get(0));
}
else
{
lines.add(" " + identifierLines.get(i));
}
}
// The description should be wrapped, if necessary. We'll also want to
// indent it (unless someone chose an absurdly small wrap width) to make
// it stand out from the argument lines.
final String description = a.getDescription();
if (maxWidth > 10)
{
final String indentString;
if (indent)
{
indentString = " ";
}
else
{
indentString = " ";
}
final List descLines = StaticUtils.wrapLine(description,
(maxWidth-indentString.length()));
for (final String s : descLines)
{
lines.add(indentString + s);
}
}
else
{
lines.addAll(StaticUtils.wrapLine(description, maxWidth));
}
}
/**
* Writes usage information for this program to the provided output stream
* using the UTF-8 encoding, optionally wrapping long lines.
*
* @param outputStream The output stream to which the usage information
* should be written. It must not be {@code null}.
* @param maxWidth The maximum line width to use for the output. If
* this is less than or equal to zero, then no wrapping
* will be performed.
*
* @throws IOException If an error occurs while attempting to write to the
* provided output stream.
*/
public void getUsage(@NotNull final OutputStream outputStream,
final int maxWidth)
throws IOException
{
final List usageLines = getUsage(maxWidth);
for (final String s : usageLines)
{
outputStream.write(StaticUtils.getBytes(s));
outputStream.write(StaticUtils.EOL_BYTES);
}
}
/**
* Retrieves a string representation of the usage information.
*
* @param maxWidth The maximum line width to use for the output. If this is
* less than or equal to zero, then no wrapping will be
* performed.
*
* @return A string representation of the usage information
*/
@NotNull()
public String getUsageString(final int maxWidth)
{
final StringBuilder buffer = new StringBuilder();
getUsageString(buffer, maxWidth);
return buffer.toString();
}
/**
* Appends a string representation of the usage information to the provided
* buffer.
*
* @param buffer The buffer to which the information should be appended.
* @param maxWidth The maximum line width to use for the output. If this is
* less than or equal to zero, then no wrapping will be
* performed.
*/
public void getUsageString(@NotNull final StringBuilder buffer,
final int maxWidth)
{
for (final String line : getUsage(maxWidth))
{
buffer.append(line);
buffer.append(StaticUtils.EOL);
}
}
/**
* Retrieves a string representation of this argument parser.
*
* @return A string representation of this argument parser.
*/
@Override()
@NotNull()
public String toString()
{
final StringBuilder buffer = new StringBuilder();
toString(buffer);
return buffer.toString();
}
/**
* Appends a string representation of this argument parser to the provided
* buffer.
*
* @param buffer The buffer to which the information should be appended.
*/
public void toString(@NotNull final StringBuilder buffer)
{
buffer.append("ArgumentParser(commandName='");
buffer.append(commandName);
buffer.append("', commandDescription={");
buffer.append('\'');
buffer.append(commandDescription);
buffer.append('\'');
if (additionalCommandDescriptionParagraphs != null)
{
for (final String additionalParagraph :
additionalCommandDescriptionParagraphs)
{
buffer.append(", '");
buffer.append(additionalParagraph);
buffer.append('\'');
}
}
buffer.append("}, minTrailingArgs=");
buffer.append(minTrailingArgs);
buffer.append(", maxTrailingArgs=");
buffer.append(maxTrailingArgs);
if (trailingArgsPlaceholder != null)
{
buffer.append(", trailingArgsPlaceholder='");
buffer.append(trailingArgsPlaceholder);
buffer.append('\'');
}
buffer.append(", namedArgs={");
final Iterator iterator = namedArgs.iterator();
while (iterator.hasNext())
{
iterator.next().toString(buffer);
if (iterator.hasNext())
{
buffer.append(", ");
}
}
buffer.append('}');
if (! subCommands.isEmpty())
{
buffer.append(", subCommands={");
final Iterator subCommandIterator = subCommands.iterator();
while (subCommandIterator.hasNext())
{
subCommandIterator.next().toString(buffer);
if (subCommandIterator.hasNext())
{
buffer.append(", ");
}
}
buffer.append('}');
}
buffer.append(')');
}
}
