Package org.apache.logging.log4j.core.tools.picocli

Annotation Type CommandLine.Parameters

  • @Retention(RUNTIME)
@Target(FIELD)
public static @interface CommandLine.Parameters

    Fields annotated with @Parameters will be initialized with positional parameters. By specifying the index() attribute you can pick which (or what range) of the positional parameters to apply. If no index is specified, the field will get all positional parameters (so it should be an array or a collection).

    When parsing the command line arguments, picocli first tries to match arguments to Options. Positional parameters are the arguments that follow the options, or the arguments that follow a "--" (double dash) argument on the command line.

    For example: 

    import static picocli.CommandLine.*;

 public class MyCalcParameters {
     @Parameters(type = BigDecimal.class, description = "Any number of input numbers")
     private List<BigDecimal> files = new ArrayList<BigDecimal>();

     @Option(names = { "-h", "--help", "-?", "-help"}, help = true, description = "Display this help and exit")
     private boolean help;
 }

    A field cannot be annotated with both @Parameters and @Option or a ParameterException is thrown.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      java.lang.String arity
      Specifies the minimum number of required parameters and the maximum number of accepted parameters.
      java.lang.String[] description
      Description of the parameter(s), used when generating the usage documentation.
      boolean hidden
      Set hidden=true if this parameter should not be included in the usage message.
      java.lang.String index
      Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this field.
      java.lang.String paramLabel
      Specify a paramLabel for the parameter to be used in the usage help message.
      java.lang.String split
      Specify a regular expression to use to split positional parameter values before applying them to the field.
      java.lang.Class<?>[] type
      Optionally specify a type to control exactly what Class the positional parameter should be converted to.

    • Element Detail

      • index

        java.lang.String index
        Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this field. For array or Collection fields, you can also specify an index range ("0..3", or "2..*", etc.) to assign a subset of the command line arguments to this field. The default is "*", meaning all command line arguments.
        Returns:
        an index or range specifying which of the command line arguments should be assigned to this field
        Default:
        "*"

      • description

        java.lang.String[] description
        Description of the parameter(s), used when generating the usage documentation.
        Returns:
        the description of the parameter(s)
        Default:
        {}

      • arity

        java.lang.String arity
        Specifies the minimum number of required parameters and the maximum number of accepted parameters. If a positive arity is declared, and the user specifies an insufficient number of parameters on the command line, CommandLine.MissingParameterException is thrown by the CommandLine.parse(String...) method.

        The default depends on the type of the parameter: booleans require no parameters, arrays and Collections accept zero to any number of parameters, and any other type accepts one parameter.

        Returns:
        the range of minimum and maximum parameters accepted by this command
        Default:
        ""

      • paramLabel

        java.lang.String paramLabel
        Specify a paramLabel for the parameter to be used in the usage help message. If omitted, picocli uses the field name in fish brackets ('<' and '>') by default. Example: 
        class Example {
     @Parameters(paramLabel="FILE", description="path of the input FILE(s)")
     private File[] inputFiles;
 }

        By default, the above gives a usage help message like the following:

         Usage: <main class> [FILE...]
 [FILE...]       path of the input FILE(s)
        Returns:
        name of the positional parameter used in the usage help message
        Default:
        ""

      • type

        java.lang.Class<?>[] type

        Optionally specify a type to control exactly what Class the positional parameter should be converted to. This may be useful when the field type is an interface or an abstract class. For example, a field can be declared to have type java.lang.Number, and annotating @Parameters(type=Short.class) ensures that the positional parameter value is converted to a Short before setting the field value.

        For array fields whose component type is an interface or abstract class, specify the concrete component type. For example, a field with type Number[] may be annotated with @Parameters(type=Short.class) to ensure that positional parameter values are converted to Short before adding an element to the array.

        Picocli will use the CommandLine.ITypeConverter that is registered for the specified type to convert the raw String values before modifying the field value.

        Prior to 2.0, the type attribute was necessary for Collection and Map fields, but starting from 2.0 picocli will infer the component type from the generic type's type arguments. For example, for a field of type Map<TimeUnit, Long> picocli will know the positional parameter should be split up in key=value pairs, where the key should be converted to a java.util.concurrent.TimeUnit enum value, and the value should be converted to a Long. No @Parameters(type=...) type attribute is required for this. For generic types with wildcards, picocli will take the specified upper or lower bound as the Class to convert to, unless the @Parameters annotation specifies an explicit type attribute.

        If the field type is a raw collection or a raw map, and you want it to contain other values than Strings, or if the generic type's type arguments are interfaces or abstract classes, you may specify a type attribute to control the Class that the positional parameter should be converted to.

        Returns:
        the type(s) to convert the raw String values
        Default:
        {}

      • split

        java.lang.String split
        Specify a regular expression to use to split positional parameter values before applying them to the field. All elements resulting from the split are added to the array or Collection. Ignored for single-value fields.
        Returns:
        a regular expression to split operand values or "" if the value should not be split
        See Also:
        String.split(String)
        Default:
        ""

      • hidden

        boolean hidden
        Set hidden=true if this parameter should not be included in the usage message.
        Returns:
        whether this parameter should be excluded from the usage message
        Default:
        false