Class JCommander

java.lang.Object
com.beust.jcommander.JCommander

public class JCommander extends Object
The main class for JCommander. It's responsible for parsing the object that contains all the annotated fields, parse the command line and assign the fields with the correct values and a few other helper methods, such as usage(). The object(s) you pass in the constructor are expected to have one or more \@Parameter annotations on them. You can pass either a single object, an array of objects or an instance of Iterable. In the case of an array or Iterable, JCommander will collect the \@Parameter annotations from all the objects passed in parameter.
  • Field Details

    • DEBUG_PROPERTY

      public static final String DEBUG_PROPERTY
      See Also:
    • descriptions

      private Map<FuzzyMap.IKey,ParameterDescription> descriptions
      A map to look up parameter description per option name.
    • objects

      private List<Object> objects
      The objects that contain fields annotated with @Parameter.
    • usageFormatter

      private IUsageFormatter usageFormatter
      The usage formatter to use in usage().
    • mainParameter

      private JCommander.MainParameter mainParameter
    • requiredFields

      private Map<Parameterized,ParameterDescription> requiredFields
      A set of all the parameterizeds that are required. During the reflection phase, this field receives all the fields that are annotated with required=true and during the parsing phase, all the fields that are assigned a value are removed from it. At the end of the parsing phase, if it's not empty, then some required fields did not receive a value and an exception is thrown.
    • fields

      A map of all the parameterized fields/methods.
    • commands

      List of commands and their instance.
    • aliasMap

      Alias database for reverse lookup
    • parsedCommand

      private String parsedCommand
      The name of the command after the parsing has run.
    • parsedAlias

      private String parsedAlias
      The name of command or alias as it was passed to the command line
    • programName

      private JCommander.ProgramName programName
    • helpWasSpecified

      private boolean helpWasSpecified
    • unknownArgs

      private List<String> unknownArgs
    • console

      private Console console
    • options

      private final JCommander.Options options
    • DEFAULT_VARIABLE_ARITY

      private final IVariableArity DEFAULT_VARIABLE_ARITY
  • Constructor Details

    • JCommander

      private JCommander(JCommander.Options options)
    • JCommander

      public JCommander()
      Creates a new un-configured JCommander object.
    • JCommander

      public JCommander(Object object)
      Parameters:
      object - The arg object expected to contain Parameter annotations.
    • JCommander

      public JCommander(Object object, ResourceBundle bundle)
      Parameters:
      object - The arg object expected to contain Parameter annotations.
      bundle - The bundle to use for the descriptions. Can be null.
    • JCommander

      public JCommander(Object object, ResourceBundle bundle, String... args)
      Parameters:
      object - The arg object expected to contain Parameter annotations.
      bundle - The bundle to use for the descriptions. Can be null.
      args - The arguments to parse (optional).
    • JCommander

      @Deprecated public JCommander(Object object, String... args)
      Deprecated.
      Construct a JCommander instance first and then call parse() on it.
      Parameters:
      object - The arg object expected to contain Parameter annotations.
      args - The arguments to parse (optional).
  • Method Details

    • setExpandAtSign

      public void setExpandAtSign(boolean expandAtSign)
      Disables expanding @file. JCommander supports the @file syntax, which allows you to put all your options into a file and pass this file as parameter @param expandAtSign whether to expand @file.
    • setConsole

      public void setConsole(Console console)
    • getConsole

      public Console getConsole()
      Returns:
      a wrapper for a PrintStream, typically System.out.
    • addObject

      public final void addObject(Object object)
      Adds the provided arg object to the set of objects that this commander will parse arguments into.
      Parameters:
      object - The arg object expected to contain Parameter annotations. If object is an array or is Iterable, the child objects will be added instead.
    • setDescriptionsBundle

      public final void setDescriptionsBundle(ResourceBundle bundle)
      Sets the ResourceBundle to use for looking up descriptions. Set this to null to use description text directly.
    • parse

      public void parse(String... args)
      Parse and validate the command line parameters.
    • parseWithoutValidation

      public void parseWithoutValidation(String... args)
      Parse the command line parameters without validating them.
    • parse

      private void parse(boolean validate, String... args)
    • initializeDefaultValues

      private void initializeDefaultValues()
    • validateOptions

      private void validateOptions()
      Make sure that all the required parameters have received a value.
    • pluralize

      private static String pluralize(int quantity, String singular, String plural)
    • expandArgs

      private String[] expandArgs(String[] originalArgv)
      Expand the command line parameters to take @ parameters into account. When @ is encountered, the content of the file that follows is inserted in the command line.
      Parameters:
      originalArgv - the original command line parameters
      Returns:
      the new and enriched command line parameters
    • expandDynamicArg

      private List<String> expandDynamicArg(String arg)
    • matchArg

      private boolean matchArg(String arg, FuzzyMap.IKey key)
    • isOption

      private boolean isOption(String passedArg)
    • getPrefixDescriptionFor

      private ParameterDescription getPrefixDescriptionFor(String arg)
    • getDescriptionFor

      private ParameterDescription getDescriptionFor(String arg)
      If arg is an option, we can look it up directly, but if it's a value, we need to find the description for the option that precedes it.
    • getSeparatorFor

      private String getSeparatorFor(String arg)
    • readFile

      private List<String> readFile(String fileName)
      Reads the file specified by filename and returns the file content as a string. End of lines are replaced by a space.
      Parameters:
      fileName - the command line filename
      Returns:
      the file content as a string.
    • trim

      private static String trim(String string)
      Remove spaces at both ends and handle double quotes.
    • createDescriptions

      public void createDescriptions()
      Create the ParameterDescriptions for all the \@Parameter found.
    • addDescription

      private void addDescription(Object object)
    • initializeDefaultValue

      private void initializeDefaultValue(ParameterDescription pd)
    • parseValues

      private void parseValues(String[] args, boolean validate)
      Main method that parses the values and initializes the fields accordingly.
    • isBooleanType

      private boolean isBooleanType(Class<?> fieldType)
    • handleBooleanOption

      private void handleBooleanOption(ParameterDescription pd, Class<?> fieldType)
    • determineArity

      private final int determineArity(String[] args, int index, ParameterDescription pd, IVariableArity va)
    • processPassword

      private int processPassword(String[] args, int index, ParameterDescription pd, boolean validate)
      Returns:
      the number of options that were processed.
    • processVariableArity

      private int processVariableArity(String[] args, int index, ParameterDescription pd, boolean validate)
      Returns:
      the number of options that were processed.
    • processFixedArity

      private int processFixedArity(String[] args, int index, ParameterDescription pd, boolean validate, Class<?> fieldType)
    • processFixedArity

      private int processFixedArity(String[] args, int originalIndex, ParameterDescription pd, boolean validate, Class<?> fieldType, int arity)
    • readPassword

      private char[] readPassword(String description, boolean echoInput)
      Invoke Console.readPassword through reflection to avoid depending on Java 6.
    • subArray

      private String[] subArray(String[] args, int index)
    • initMainParameterValue

      private void initMainParameterValue(String arg)
      Init the main parameter with the given arg. Note that the main parameter can be either a List or a single value.
    • getMainParameterDescription

      public String getMainParameterDescription()
    • setProgramName

      public void setProgramName(String name)
      Set the program name (used only in the usage).
    • getProgramName

      public String getProgramName()
      Get the program name (used only in the usage).
    • getProgramDisplayName

      public String getProgramDisplayName()
      Get the program display name (used only in the usage).
    • setProgramName

      public void setProgramName(String name, String... aliases)
      Set the program name
      Parameters:
      name - program name
      aliases - aliases to the program name
    • usage

      public void usage()
      Prints the usage on getConsole() using the underlying usageFormatter.
    • setUsageFormatter

      public void setUsageFormatter(IUsageFormatter usageFormatter)
      Sets the usage formatter.
      Parameters:
      usageFormatter - the usage formatter
      Throws:
      IllegalArgumentException - if the argument is null
    • getUsageFormatter

      public IUsageFormatter getUsageFormatter()
      Returns the usage formatter.
      Returns:
      the usage formatter
    • getOptions

      public JCommander.Options getOptions()
    • getDescriptions

      public Map<FuzzyMap.IKey,ParameterDescription> getDescriptions()
    • getMainParameter

      public JCommander.MainParameter getMainParameter()
    • newBuilder

      public static JCommander.Builder newBuilder()
    • getFields

      public Map<Parameterized,ParameterDescription> getFields()
    • getParameterDescriptionComparator

      public Comparator<? super ParameterDescription> getParameterDescriptionComparator()
    • setParameterDescriptionComparator

      public void setParameterDescriptionComparator(Comparator<? super ParameterDescription> c)
    • setColumnSize

      public void setColumnSize(int columnSize)
    • getColumnSize

      public int getColumnSize()
    • getBundle

      public ResourceBundle getBundle()
    • getParameters

      public List<ParameterDescription> getParameters()
      Returns:
      a Collection of all the \@Parameter annotations found on the target class. This can be used to display the usage() in a different format (e.g. HTML).
    • getMainParameterValue

      public ParameterDescription getMainParameterValue()
      Returns:
      the main parameter description or null if none is defined.
    • p

      private void p(String string)
    • setDefaultProvider

      public void setDefaultProvider(IDefaultProvider defaultProvider)
      Define the default provider for this instance.
    • addConverterFactory

      public void addConverterFactory(IStringConverterFactory converterFactory)
      Adds a factory to lookup string converters. The added factory is used prior to previously added factories.
      Parameters:
      converterFactory - the factory determining string converters
    • addConverterInstanceFactory

      public void addConverterInstanceFactory(IStringConverterInstanceFactory converterInstanceFactory)
      Adds a factory to lookup string converters. The added factory is used prior to previously added factories.
      Parameters:
      converterInstanceFactory - the factory generating string converter instances
    • findConverterInstance

      private IStringConverter<?> findConverterInstance(Parameter parameter, Class<?> forType, String optionName)
    • convertValue

      public Object convertValue(Parameterized parameterized, Class type, String optionName, String value)
      Parameters:
      type - The type of the actual parameter
      optionName -
      value - The value to convert
    • tryInstantiateConverter

      private static <T> T tryInstantiateConverter(String optionName, Class<T> converterClass)
    • instantiateConverter

      private static <T> T instantiateConverter(String optionName, Class<? extends T> converterClass) throws InstantiationException, IllegalAccessException, InvocationTargetException
      Throws:
      InstantiationException
      IllegalAccessException
      InvocationTargetException
    • addCommand

      public void addCommand(String name, Object object)
      Add a command object.
    • addCommand

      public void addCommand(Object object)
    • addCommand

      public void addCommand(String name, Object object, String... aliases)
      Add a command object and its aliases.
    • getCommands

      public Map<String,JCommander> getCommands()
    • getRawCommands

      public Map<JCommander.ProgramName,JCommander> getRawCommands()
    • getParsedCommand

      public String getParsedCommand()
    • getParsedAlias

      public String getParsedAlias()
      The name of the command or the alias in the form it was passed to the command line. null if no command or alias was specified.
      Returns:
      Name of command or alias passed to command line. If none passed: null.
    • s

      private String s(int count)
      Returns:
      n spaces
    • getObjects

      public List<Object> getObjects()
      Returns:
      the objects that JCommander will fill with the result of parsing the command line.
    • findParameterDescription

      private ParameterDescription findParameterDescription(String arg)
    • findCommand

      private JCommander findCommand(JCommander.ProgramName name)
    • findProgramName

      private JCommander.ProgramName findProgramName(String name)
    • findCommandByAlias

      public JCommander findCommandByAlias(String commandOrAlias)
    • setVerbose

      public void setVerbose(int verbose)
    • setCaseSensitiveOptions

      public void setCaseSensitiveOptions(boolean b)
    • setAllowAbbreviatedOptions

      public void setAllowAbbreviatedOptions(boolean b)
    • setAcceptUnknownOptions

      public void setAcceptUnknownOptions(boolean b)
    • getUnknownOptions

      public List<String> getUnknownOptions()
    • setAllowParameterOverwriting

      public void setAllowParameterOverwriting(boolean b)
    • isParameterOverwritingAllowed

      public boolean isParameterOverwritingAllowed()
    • setAtFileCharset

      public void setAtFileCharset(Charset charset)
      Sets the charset used to expand @files.
      Parameters:
      charset - the charset