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
`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
`static CommandLine.Model.PositionalParamSpec.Builder` `builder()`
`static CommandLine.Model.PositionalParamSpec.Builder` `builder(CommandLine.Model.IAnnotatedElement source, CommandLine.IFactory factory)`
`boolean` `equals(Object obj)`
`protected Collection<String>` `getAdditionalDescriptionKeys()` Returns the additional lookup keys for finding description lines in the resource bundle for this positional parameter.
`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, description, descriptionKey, equalsImpl, getter, getValue, group, hashCodeImpl, hasInitialValue, hidden, hideParamSyntax, initialValue, interactive, internalShowDefaultValue, isMultiValue, messages, messages, originalStringValues, paramLabel, renderedDescription, required, resetOriginalStringValues, resetStringValues, scope, setter, setValue, setValue, showDefaultValue, splitRegex, stringValues, toString, type, typedValues, typeInfo, userObject`

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

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

### Method Detail

#### builder

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

#### builder

    public static CommandLine.Model.PositionalParamSpec.Builder builder(CommandLine.Model.IAnnotatedElement source,
                                                                        CommandLine.IFactory factory)

#### 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`

#### getAdditionalDescriptionKeys

    protected Collection<String> getAdditionalDescriptionKeys()

Returns the additional lookup keys for finding description lines in the resource bundle for this positional parameter.

Specified by:
  `getAdditionalDescriptionKeys` in class `CommandLine.Model.ArgSpec`
Returns:
  a collection with the following single value: `paramLabel() + "[" + index() + "]"`.
Since:
  4.0
See Also:
  `CommandLine.Model.OptionSpec.getAdditionalDescriptionKeys()`, `getAdditionalDescriptionKeys()`

#### 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()`

#### hashCode

    public int hashCode()

Overrides:
  `hashCode` in class `Object`

#### equals

    public boolean equals(Object obj)

Overrides:
  `equals` in class `Object`