picocli

## Annotation Type CommandLine.Parameters

-     @Retention(value=RUNTIME)
       @Target(value={FIELD,METHOD,PARAMETER})
      public static @interface CommandLine.Parameters

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

  In the case of command methods (annotated with `@Command`), method parameters may be annotated with `@Parameters`, but are are considered positional parameters by default, unless they are annotated with `@Option`.

  Command class example:

       import static picocli.CommandLine.*;

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

           @Option(names = { "-h", "--help" }, usageHelp = 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 and Description
    --- | ---
    `String` | `arity` Specifies the minimum number of required parameters and the maximum number of accepted parameters.
    `Class<? extends Iterable<String>>` | `completionCandidates` Use this attribute to specify an `Iterable<String>` class that generates completion candidates for this positional parameter.
    `Class<? extends CommandLine.ITypeConverter<?>>[]` | `converter` Optionally specify one or more `CommandLine.ITypeConverter` classes to use to convert the command line argument into a strongly typed value (or key-value pair for map fields).
    `String` | `defaultValue` Returns the default value of this positional parameter, before splitting and type conversion.
    `String[]` | `description` Description of the parameter(s), used when generating the usage documentation.
    `String` | `descriptionKey` ResourceBundle key for this option.
    `boolean` | `hidden` Set `hidden=true` if this parameter should not be included in the usage message.
    `boolean` | `hideParamSyntax` Returns whether usage syntax decorations around the paramLabel should be suppressed.
    `String` | `index` Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this field.
    `boolean` | `interactive` Set `interactive=true` if this positional parameter will prompt the end user for a value (like a password).
    `String` | `paramLabel` Specify a `paramLabel` for the parameter to be used in the usage help message.
    `CommandLine.Help.Visibility` | `showDefaultValue` Use this attribute to control for a specific positional parameter whether its default value should be shown in the usage help message.
    `String` | `split` Specify a regular expression to use to split positional parameter values before applying them to the field.
    `Class<?>[]` | `type` Optionally specify a `type` to control exactly what Class the positional parameter should be converted to.

- - ### Element Detail

    - #### index

          public abstract 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

          public abstract String[] description

      Description of the parameter(s), used when generating the usage documentation.

      From picocli 3.2, the usage string may contain variables that are rendered when help is requested. The string `${DEFAULT-VALUE}` is replaced with the default value of the positional parameter. This is regardless of the command's `showDefaultValues` setting or the positional parameter's `showDefaultValue` setting. The string `${COMPLETION-CANDIDATES}` is replaced with the completion candidates generated by `completionCandidates()` in the description for this positional parameter. Also, embedded `%n` newline markers are converted to actual newlines.

      Returns:
        the description of the parameter(s)
      Default:
        {}

  - - #### arity

          public abstract 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

          public abstract 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:
        ""

  - - #### hideParamSyntax

          public abstract boolean hideParamSyntax

      Returns whether usage syntax decorations around the paramLabel should be suppressed. The default is `false`: by default, the paramLabel is surrounded with `'['` and `']'` characters if the value is optional and followed by ellipses ("...") when multiple values can be specified.
      Since:
        3.6.0
      Default:
        false

  - - #### type

          public abstract 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:
        {}

  - - #### converter

          public abstract Class<? extends CommandLine.ITypeConverter<?>>[] converter

      Optionally specify one or more `CommandLine.ITypeConverter` classes to use to convert the command line argument into a strongly typed value (or key-value pair for map fields). This is useful when a particular field should use a custom conversion that is different from the normal conversion for the field's type.

      For example, for a specific field you may want to use a converter that maps the constant names defined in `java.sql.Types` to the `int` value of these constants, but any other `int` fields should not be affected by this and should continue to use the standard int converter that parses numeric values.

      Returns:
        the type converter(s) to use to convert String values to strongly typed values for this field
      See Also:
        `CommandLine.registerConverter(Class, ITypeConverter)`
      Default:
        {}

  - - #### split

          public abstract 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

          public abstract 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

  - - #### defaultValue

          public abstract String defaultValue

      Returns the default value of this positional parameter, before splitting and type conversion.
      Returns:
        a String that (after type conversion) will be used as the value for this positional parameter if no value was specified on the command line
      Since:
        3.2
      Default:
        "__no_default_value__"

  - - #### showDefaultValue

          public abstract CommandLine.Help.Visibility showDefaultValue

      Use this attribute to control for a specific positional parameter whether its default value should be shown in the usage help message. If not specified, the default value is only shown when the `CommandLine.Command.showDefaultValues()` is set `true` on the command. Use this attribute to specify whether the default value for this specific positional parameter should always be shown or never be shown, regardless of the command setting.

      Note that picocli 3.2 allows embedding default values anywhere in the description that ignores this setting.

      Returns:
        whether this positional parameter's default value should be shown in the usage help message
      Default:
        picocli.CommandLine.Help.Visibility.ON_DEMAND

  - - #### completionCandidates

          public abstract Class<? extends Iterable<String>> completionCandidates

      Use this attribute to specify an `Iterable<String>` class that generates completion candidates for this positional parameter. For map fields, completion candidates should be in `key=value` form.

      Completion candidates are used in bash completion scripts generated by the `picocli.AutoComplete` class. Unfortunately, `picocli.AutoComplete` is not very good yet at generating completions for positional parameters.

      Returns:
        a class whose instances can iterate over the completion candidates for this positional parameter
      Since:
        3.2
      See Also:
        `CommandLine.IFactory`
      Default:
        picocli.CommandLine.NoCompletionCandidates.class

  - - #### interactive

          public abstract boolean interactive

      Set `interactive=true` if this positional parameter will prompt the end user for a value (like a password). Only supported for single-value positional parameters (not arrays, collections or maps). When running on Java 6 or greater, this will use the `Console.readPassword()` API to get a value without echoing input to the console.
      Returns:
        whether this positional parameter prompts the end user for a value to be entered on the command line
      Since:
        3.5
      Default:
        false

  - - #### descriptionKey

          public abstract String descriptionKey

      ResourceBundle key for this option. If not specified, (and a ResourceBundle exists for this command) an attempt is made to find the positional parameter description using `paramLabel() + "[" + index() + "]"` as key.
      Since:
        3.6
      See Also:
        `CommandLine.Model.PositionalParamSpec.description()`
      Default:
        ""

Copyright © 2020. All rights reserved.