CommandLine.Model.PositionalParamSpec (picocli 3.9.6 API)
Date: 2019-04-06

picocli

## Class CommandLine.Model.PositionalParamSpec

- java.lang.Object
- - picocli.CommandLine.Model.ArgSpec
  - - picocli.CommandLine.Model.PositionalParamSpec

- Enclosing class:
    CommandLine.Model

      public static class CommandLine.Model.PositionalParamSpec
      extends CommandLine.Model.ArgSpec

  The `PositionalParamSpec` class models aspects of a positional parameter of a command, including whether it is required or optional, and attributes for the usage help message describing the positional parameter.

  Positional parameters have an `index` (or a range of indices). A positional parameter is matched when the parser encounters a command line argument at that index. Named options and their parameters do not change the index counter, so the command line can contain a mixture of positional parameters and named options.

  Depending on the positional parameter's `arity`, the parser may consume multiple command line arguments starting from the current index. The parser will call `setValue` on the `PositionalParamSpec` for each of the parameters encountered. For multi-value positional parameters, the `type` may be an array, a `Collection` or a `Map`. In this case the parser will get the data structure by calling `getValue` and modify the contents of this data structure. (In the case of arrays, the array is replaced with a new instance with additional elements.)

  Before calling the setter, picocli converts the positional parameter value from a String to the parameter's type.

  - If a positional parameter-specific `converter` is configured, this will be used for type conversion. If the positional parameter's type is a `Map`, the map may have different types for its keys and its values, so `converters` should provide two converters: one for the map keys and one for the map values.
  - Otherwise, the positional parameter's `type` is used to look up a converter in the list of registered converters. For multi-value positional parameters, the `type` may be an array, or a `Collection` or a `Map`. In that case the elements are converted based on the positional parameter's `auxiliaryTypes`. The auxiliaryType is used to look up the converter(s) to use to convert the individual parameter values. Maps may have different types for its keys and its values, so `auxiliaryTypes` should provide two types: one for the map keys and one for the map values.

  `PositionalParamSpec` objects are used by the picocli command line interpreter and help message generator. Picocli can construct a `PositionalParamSpec` automatically from fields and methods with `@Parameters` annotations. Alternatively a `PositionalParamSpec` can be constructed programmatically.

  When a `PositionalParamSpec` is created from a `@Parameters` -annotated field or method, it is "bound" to that field or method: this field is set (or the method is invoked) when the position is matched and `setValue` is called. Programmatically constructed `PositionalParamSpec` instances will remember the value passed to the `setValue` method so it can be retrieved with the `getValue` method. This behaviour can be customized by installing a custom `CommandLine.Model.IGetter` and `CommandLine.Model.ISetter` on the `PositionalParamSpec`.

  Since:
    3.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `CommandLine.Model.PositionalParamSpec.Builder` Builder responsible for creating valid `PositionalParamSpec` objects.

  - ### Field Summary

    - ### Fields inherited from class picocli.CommandLine.Model.ArgSpec

      `toString`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static CommandLine.Model.PositionalParamSpec.Builder` | `builder()`
    `java.lang.String[]` | `description()` Returns the description template of this positional parameter, before variables are rendered.
    `boolean` | `equals(java.lang.Object obj)`
    `int` | `hashCode()`
    `CommandLine.Range` | `index()` Returns an index or range specifying which of the command line arguments should be assigned to this positional parameter.
    `boolean` | `isOption()` Returns `true` if this argument is a named option, `false` otherwise.
    `boolean` | `isPositional()` Returns `true` if this argument is a positional parameter, `false` otherwise.
    `CommandLine.Model.PositionalParamSpec.Builder` | `toBuilder()` Returns a new Builder initialized with the attributes from this `PositionalParamSpec`.

    - ### Methods inherited from class picocli.CommandLine.Model.ArgSpec

      `arity, auxiliaryTypes, completionCandidates, converters, defaultValue, defaultValueString, descriptionKey, equalsImpl, getter, getValue, hashCodeImpl, hasInitialValue, hidden, hideParamSyntax, initialValue, interactive, internalShowDefaultValue, isMultiValue, messages, messages, originalStringValues, paramLabel, renderedDescription, required, resetOriginalStringValues, resetStringValues, setter, setValue, setValue, showDefaultValue, splitRegex, stringValues, toString, type, typedValues`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### toBuilder

          public CommandLine.Model.PositionalParamSpec.Builder toBuilder()

      Returns a new Builder initialized with the attributes from this `PositionalParamSpec`. Calling `build` immediately will return a copy of this `PositionalParamSpec`.
      Returns:
        a builder that can create a copy of this spec

    - #### isOption

          public boolean isOption()

      Description copied from class: `CommandLine.Model.ArgSpec`
      Returns `true` if this argument is a named option, `false` otherwise.
      Specified by:
        `isOption` in class `CommandLine.Model.ArgSpec`

    - #### isPositional

          public boolean isPositional()

      Description copied from class: `CommandLine.Model.ArgSpec`
      Returns `true` if this argument is a positional parameter, `false` otherwise.
      Specified by:
        `isPositional` in class `CommandLine.Model.ArgSpec`

    - #### description

          public java.lang.String[] description()

      Returns the description template of this positional parameter, before variables are rendered. If a resource bundle has been set, this method will first try to find a value in the resource bundle: If the resource bundle has no entry for the `fully qualified commandName + "." + descriptionKey` or for the unqualified `descriptionKey`, an attempt is made to find the positional parameter description using `paramLabel() + "[" + index() + "]"` as key, first with the `fully qualified commandName + "."` prefix, then without.
      Overrides:
        `description` in class `CommandLine.Model.ArgSpec`
      Since:
        3.6
      See Also:
        `CommandLine.Parameters.description()`, `CommandLine.Model.CommandSpec.qualifiedName(String)`

    - #### index

          public CommandLine.Range index()

      Returns an index or range specifying which of the command line arguments should be assigned to this positional parameter.
      See Also:
        `CommandLine.Parameters.index()`

    - #### builder

          public static CommandLine.Model.PositionalParamSpec.Builder builder()

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object obj)

      Overrides:
        `equals` in class `java.lang.Object`