CommandLine.Model.OptionSpec (picocli 4.6.3 API)

picocli

## Class CommandLine.Model.OptionSpec

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

- All Implemented Interfaces:
    CommandLine.Model.IOrdered
  Enclosing class:
    CommandLine.Model

      public static class CommandLine.Model.OptionSpec
      extends CommandLine.Model.ArgSpec
      implements CommandLine.Model.IOrdered

  The `OptionSpec` class models aspects of a named option of a command, including whether it is required or optional, the option parameters supported (or required) by the option, and attributes for the usage help message describing the option.

  An option has one or more names. The option is matched when the parser encounters one of the option names in the command line arguments. Depending on the option's `arity`, the parser may expect it to have option parameters. The parser will call `setValue` on the matched option for each of the option parameters encountered.

  For multi-value options, 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 option parameter value from a String to the option parameter's type.

  - If a option-specific `converter` is configured, this will be used for type conversion. If the option'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 option's `type` is used to look up a converter in the list of registered converters. For multi-value options, the `type` may be an array, or a `Collection` or a `Map`. In that case the elements are converted based on the option'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.

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

  When an `OptionSpec` is created from an `@Option` -annotated field or method, it is "bound" to that field or method: this field is set (or the method is invoked) when the option is matched and `setValue` is called. Programmatically constructed `OptionSpec` 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 `OptionSpec`.

  Since:
    3.0

- - ### Nested Class Summary

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

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_FALLBACK_VALUE`

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

      `annotatedElement, toString, typeInfo`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static CommandLine.Model.OptionSpec.Builder` | `builder(CommandLine.Model.IAnnotatedElement source, CommandLine.IFactory factory)`
    `static CommandLine.Model.OptionSpec.Builder` | `builder(CommandLine.Model.OptionSpec original)` Returns a Builder initialized from the specified `OptionSpec`.
    `static CommandLine.Model.OptionSpec.Builder` | `builder(String[] names)`
    `static CommandLine.Model.OptionSpec.Builder` | `builder(String name, String... names)`
    `boolean` | `equals(Object obj)`
    `String` | `fallbackValue()` Returns the fallback value for this option: the value that is assigned for options with an optional parameter (for example, `arity = "0..1"`) if the option was specified on the command line without parameter.
    `protected Collection<String>` | `getAdditionalDescriptionKeys()` Returns the additional lookup keys for finding description lines in the resource bundle for this option.
    `int` | `hashCode()`
    `boolean` | `help()` Deprecated. Use `usageHelp()` and `versionHelp()` instead.
    `protected boolean` | `internalShowDefaultValue(boolean usageMessageShowDefaults)` Returns whether the default for this option or positional parameter should be shown, potentially overriding the specified global setting.
    `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.
    `String` | `longestName()` Returns the longest option name.
    `String[]` | `names()` Returns one or more option names.
    `boolean` | `negatable()` Returns whether a negative version for this boolean option is automatically added.
    `int` | `order()` Returns the position in the options list in the usage help message at which this option should be shown.
    `String` | `shortestName()` Returns the shortest option name.
    `CommandLine.Model.OptionSpec.Builder` | `toBuilder()` Returns a new Builder initialized with the attributes from this `OptionSpec`.
    `boolean` | `usageHelp()` Returns whether this option allows the user to request usage help.
    `boolean` | `versionHelp()` Returns whether this option allows the user to request version information.

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

      `arity, auxiliaryTypes, command, completionCandidates, converters, defaultValue, defaultValueString, defaultValueString, description, descriptionKey, echo, equalsImpl, getter, getValue, group, hashCodeImpl, hasInitialValue, hidden, hideParamSyntax, inherited, initialValue, interactive, isMultiValue, mapFallbackValue, messages, messages, originalStringValues, parameterConsumer, paramLabel, preprocessor, prompt, renderedDescription, required, resetOriginalStringValues, resetStringValues, root, scope, scopeType, setter, setValue, setValue, showDefaultValue, splitRegex, splitRegexSynopsisLabel, stringValues, toString, type, typedValues, typeInfo, userObject`

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

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

- - ### Field Detail

    - #### DEFAULT_FALLBACK_VALUE

          public static final String DEFAULT_FALLBACK_VALUE

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### builder

          public static CommandLine.Model.OptionSpec.Builder builder(String name,
                                                                     String... names)

    - #### builder

          public static CommandLine.Model.OptionSpec.Builder builder(String[] names)

    - #### builder

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

    - #### builder

          public static CommandLine.Model.OptionSpec.Builder builder(CommandLine.Model.OptionSpec original)

      Returns a Builder initialized from the specified `OptionSpec`.
      Since:
        4.0

    - #### toBuilder

          public CommandLine.Model.OptionSpec.Builder toBuilder()

      Returns a new Builder initialized with the attributes from this `OptionSpec`. Calling `build` immediately will return a copy of this `OptionSpec`.
      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`

    - #### internalShowDefaultValue

          protected boolean internalShowDefaultValue(boolean usageMessageShowDefaults)

      Description copied from class: `CommandLine.Model.ArgSpec`
      Returns whether the default for this option or positional parameter should be shown, potentially overriding the specified global setting.
      Overrides:
        `internalShowDefaultValue` in class `CommandLine.Model.ArgSpec`
      Parameters:
        `usageMessageShowDefaults` - whether the command's UsageMessageSpec is configured to show default values.

    - #### getAdditionalDescriptionKeys

          protected Collection<String> getAdditionalDescriptionKeys()

      Returns the additional lookup keys for finding description lines in the resource bundle for this option.
      Specified by:
        `getAdditionalDescriptionKeys` in class `CommandLine.Model.ArgSpec`
      Returns:
        option names (after variable interpolation), without leading hyphens, slashes and other non-Java identifier characters.
      Since:
        4.0
      See Also:
        `getAdditionalDescriptionKeys()`, `CommandLine.Model.PositionalParamSpec.getAdditionalDescriptionKeys()`

    - #### names

          public String[] names()

      Returns one or more option names. The returned array will contain at least one option name.
      See Also:
        `CommandLine.Option.names()`

    - #### longestName

          public String longestName()

      Returns the longest option name.

    - #### shortestName

          public String shortestName()

      Returns the shortest option name.
      Since:
        3.8

    - #### order

          public int order()

      Returns the position in the options list in the usage help message at which this option should be shown. Options with a lower number are shown before options with a higher number. This attribute is only honored if `CommandLine.Model.UsageMessageSpec.sortOptions()` is `false` for this command.
      Specified by:
        `order` in interface `CommandLine.Model.IOrdered`
      Since:
        3.9
      See Also:
        `CommandLine.Option.order()`

    - #### help

          @Deprecated
          public boolean help()

      Deprecated. Use `usageHelp()` and `versionHelp()` instead.
      Returns whether this option disables validation of the other arguments.
      See Also:
        `CommandLine.Option.help()`

    - #### usageHelp

          public boolean usageHelp()

      Returns whether this option allows the user to request usage help.
      See Also:
        `CommandLine.Option.usageHelp()`

    - #### versionHelp

          public boolean versionHelp()

      Returns whether this option allows the user to request version information.
      See Also:
        `CommandLine.Option.versionHelp()`

    - #### negatable

          public boolean negatable()

      Returns whether a negative version for this boolean option is automatically added. The form of the negative name is determined by the `CommandLine.INegatableOptionTransformer`.
      Since:
        4.0
      See Also:
        `CommandLine.Option.negatable()`

    - #### fallbackValue

          public String fallbackValue()

      Returns the fallback value for this option: the value that is assigned for options with an optional parameter (for example, `arity = "0..1"`) if the option was specified on the command line without parameter.

      If the special value `CommandLine.Model.ArgSpec.NULL_VALUE` is set, this method returns `null`.

      Since:
        4.0
      See Also:
        `CommandLine.Option.fallbackValue()`, `CommandLine.Model.ArgSpec.defaultValue()`

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`